Sphinx doc

.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

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."
+)

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

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
 

docs/api/net.rst

@@ -0,0 +1,8 @@
+************
+Networking
+************
+
+A custom protocol built on top of QUIC.
+Using UDP over port 4242
+
+.. doxygennamespace:: net

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

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

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']

docs/index.rst

@@ -0,0 +1,16 @@
+Univerxel
+=========
+
+.. toctree::
+   :caption: API
+   :maxdepth: 2
+
+   api/world
+   api/render
+   api/net
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   todo

docs/todo.rst

@@ -0,0 +1,3 @@
+*****************
+Features and TODO
+*****************