From ab5187cbb2d584f224309af41af9c52d3fe13820 Mon Sep 17 00:00:00 2001 From: Shu Date: Thu, 5 Nov 2020 13:14:28 +0100 Subject: [PATCH] Sphinx doc --- .gitlab-ci.yml | 30 +++++++++++--- CMakeLists.txt | 8 ++++ Doxyfile | 4 +- README.md | 4 +- docs/_static/univerxel.small.png | 3 ++ docs/api/net.rst | 8 ++++ docs/api/render.rst | 16 +++++++ docs/api/world.rst | 8 ++++ docs/conf.py | 71 ++++++++++++++++++++++++++++++++ docs/index.rst | 16 +++++++ docs/todo.rst | 3 ++ 11 files changed, 162 insertions(+), 9 deletions(-) create mode 100644 docs/_static/univerxel.small.png create mode 100644 docs/api/net.rst create mode 100644 docs/api/render.rst create mode 100644 docs/api/world.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/todo.rst diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 4d0b8e9..a493d57 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,16 +1,15 @@ image: gcc -before_script: - - apt-get update - - apt-get install -y --no-install-recommends cmake libssl-dev libvulkan-dev xorg-dev doxygen graphviz - build: stage: build + before_script: + - apt-get update + - apt-get install -y --no-install-recommends cmake libssl-dev libvulkan-dev xorg-dev script: - mkdir build # compile - cd build - cmake .. - - make -j2 univerxel univerxel-client univerxel-server docs + - make -j2 univerxel univerxel-client univerxel-server - mkdir -p ../out/full ../out/client ../out/server/content # package artifacts - cp -r univerxel content ../out/full - cp -r univerxel-client content ../out/client @@ -22,8 +21,27 @@ build: - out/full - out/client - out/server - - build/docs expire_in: 1 week # cache: # paths: # - "*.o" + +pages: + stage: deploy + before_script: + - apt-get update + - apt-get install -y --no-install-recommends cmake doxygen graphviz python3-sphinx python3-pip + - pip3 install sphinx_rtd_theme breathe myst-parser + script: + - mkdir build + - cd build + - cmake .. + - make docs pages + - mv pages ../public + artifacts: + paths: + - build/docs/html + - public + expire_in: 1 week + only: + - master \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index 7a70c4e..98b2c18 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -76,5 +76,13 @@ file(COPY resource/content DESTINATION ${CMAKE_BINARY_DIR}) add_custom_target(docs COMMAND doxygen ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile WORKING_DIRECTORY ${CMAKE_BINARY_DIR} + BYPRODUCTS ${CMAKE_BINARY_DIR}/docs ${CMAKE_BINARY_DIR}/docs/xml COMMENT "Build doc." ) +add_custom_target(pages + COMMAND sphinx-build -b html ${CMAKE_CURRENT_SOURCE_DIR}/docs ${CMAKE_BINARY_DIR}/pages + WORKING_DIRECTORY ${CMAKE_BINARY_DIR} + DEPENDS ${CMAKE_BINARY_DIR}/docs/xml + BYPRODUCTS ${CMAKE_BINARY_DIR}/pages + COMMENT "Build pages." +) \ No newline at end of file diff --git a/Doxyfile b/Doxyfile index 18f3613..bdccfe9 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1106,7 +1106,7 @@ USE_HTAGS = NO # See also: Section \class. # The default value is: YES. -VERBATIM_HEADERS = YES +VERBATIM_HEADERS = NO #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index @@ -2015,7 +2015,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of diff --git a/README.md b/README.md index f41dd63..b9d87b5 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,8 @@ To get a local copy up and running, follow these simple steps. * [glslc](https://github.com/KhronosGroup/glslang): build vk shaders * Imagemagick: build textures (convert jpg to png) * [Compressonator](https://github.com/GPUOpen-Tools/compressonator): build textures (compress dds) +* [Doxygen](https://www.doxygen.nl/index.html): API docs +* [Sphinx](https://www.sphinx-doc.org/) [rtd_theme](https://github.com/readthedocs/sphinx_rtd_theme) [Breathe](https://breathe.readthedocs.io/en/latest/): sphinx pages ### Installation @@ -113,7 +115,7 @@ univerxel | All in one univerxel-server | Standalone server univerxel-client | Light client docs | Doxygen documentation - +pages | Sphinx pages #### Additionally diff --git a/docs/_static/univerxel.small.png b/docs/_static/univerxel.small.png new file mode 100644 index 0000000..21c1e4b --- /dev/null +++ b/docs/_static/univerxel.small.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7e094ac5c20459a9811a9896544c9c3c2b1cc0a8fa92b45be01f027d1cd7e693 +size 91025 diff --git a/docs/api/net.rst b/docs/api/net.rst new file mode 100644 index 0000000..c8f935c --- /dev/null +++ b/docs/api/net.rst @@ -0,0 +1,8 @@ +************ +Networking +************ + +A custom protocol built on top of QUIC. +Using UDP over port 4242 + +.. doxygennamespace:: net \ No newline at end of file diff --git a/docs/api/render.rst b/docs/api/render.rst new file mode 100644 index 0000000..badb61c --- /dev/null +++ b/docs/api/render.rst @@ -0,0 +1,16 @@ +************ +Networking +************ + +Univerxel supports 2 render pipelines: OpenGL and Vulkan. +Driver is selected automatically at startup depending on system capabilities. + +Vulkan implementation still work in progress and not so performant. + +.. doxygennamespace:: render + + +World rendering uses Dual Contouring algorithm with embedded material selection. + +.. doxygennamespace:: contouring +.. doxygennamespace:: dualmc \ No newline at end of file diff --git a/docs/api/world.rst b/docs/api/world.rst new file mode 100644 index 0000000..d37a2e3 --- /dev/null +++ b/docs/api/world.rst @@ -0,0 +1,8 @@ +************ +World +************ + +Our univerxe is made of Voxel containing a material and density. +They are stored in many areas (Planets, ships, and more...), grouped in 32^3 chunk, them self in 32^3 region file. + +.. doxygennamespace:: world \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..7566787 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,71 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Univerxel' +copyright = '2020, Shu - MIT' +author = 'Shu' + +# The short X.Y version +version = '0.0' + +# The full version, including alpha/beta/rc tags +release = '0.0.1-alpha' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['breathe', 'sphinx_rtd_theme'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +breathe_projects = { "univerxel": "../build/docs/xml" } +breathe_default_project = "univerxel" + +# Tell sphinx what the primary language being documented is. +primary_domain = 'cpp' + +# Tell sphinx what the pygments highlight language should be. +highlight_language = 'cpp' + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' +html_logo = '_static/univerxel.small.png' +html_theme_options = { + 'canonical_url': '', + 'display_version': False, + 'style_nav_header_background': '#5c4ca2', +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..f0e01bc --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,16 @@ +Univerxel +========= + +.. toctree:: + :caption: API + :maxdepth: 2 + + api/world + api/render + api/net + +.. toctree:: + :maxdepth: 1 + :hidden: + + todo diff --git a/docs/todo.rst b/docs/todo.rst new file mode 100644 index 0000000..ba9b542 --- /dev/null +++ b/docs/todo.rst @@ -0,0 +1,3 @@ +***************** +Features and TODO +*****************