update documentation, add rst files, build step in pipeline is not needed anymore

.gitignore

@@ -13,9 +13,4 @@ docs/vale/styles/*
 venv/
 .venv/
 
-# Ignore files generated by apidoc
-docs/source/lso.rst
-docs/source/lso.*.rst
-docs/source/modules.rst
-
 config.json

build-docs.sh

@@ -5,7 +5,6 @@ export SETTINGS_FILENAME=./config.json.example
 python docs/dump-openapi-spec.py
 
 rm -r ./docs/build/*
-sphinx-apidoc lso lso/app.py -o docs/source -d 2 -f
 vale --config=docs/vale/.vale.ini sync
 vale --config=docs/vale/.vale.ini docs/source/*.rst lso/*.py
 sphinx-build -b html docs/source docs/build

docs/.gitlab-ci.yml

 ---
-##### Sphinx  - Generate documentation
-build-documentation:
-  stage: documentation
-  tags:
-    - docker-executor
-  image: sphinxdoc/sphinx:latest
-  needs:
-    - job: run-tox-pipeline
-      artifacts: true
-
-  before_script:
-    - pip install sphinx_rtd_theme
-  script:
-    - sphinx-apidoc lso lso/app.py -o docs/source -d 2 -f
-    - sphinx-build -b html docs/source docs/build
-
-  artifacts:
-    paths:
-      - $CI_PROJECT_DIR/docs/build
-
 ##### Vale    - Documentation linter
 lint-documentation:
   stage: documentation
@@ -29,8 +9,7 @@ lint-documentation:
   tags:
     - docker-executor
   needs:
-    - job: build-documentation # Only run when documentation has been built
-      artifacts: true
+    - job: run-tox-pipeline # Only run when tox has finished
 
   before_script:
     - vale --config=docs/vale/.vale.ini sync

docs/source/conf.py

@@ -75,8 +75,7 @@ html_css_files = ['custom.css']
 html_logo = '_static/geant_logo_white.svg'
 
 
-# Both the class' and the __init__ method's docstring
-# are concatenated and inserted.
+# Both the class' and the ``__init__`` method's docstring are concatenated and inserted.
 autoclass_content = 'both'
 autodoc_typehints = 'none'
 

docs/source/index.rst

-Lightweight service orchestrator
+Lightweight Service Orchestrator
 ================================
 
 Documentation for LSO (Lightweight Service Orchestrator).
@@ -8,7 +8,7 @@ Documentation for LSO (Lightweight Service Orchestrator).
    :caption: Contents:
 
    quickstart
-   lso
+   modules
 
 
-`Swagger API Docs <_static/openapi.html>`__
+`Swagger API Docs <_static/openapi.html>`_

docs/source/module/config.rst

+``lso.config``
+==============
+
+.. automodule:: lso.config
+   :members:
+   :show-inheritance:

docs/source/module/playbook.rst

+``lso.playbook``
+================
+
+.. automodule:: lso.playbook
+   :members:
+   :show-inheritance:

docs/source/module/routes/default.rst

+``lso.routes.default``
+======================
+
+.. automodule:: lso.routes.default
+   :members:
+   :show-inheritance:

docs/source/module/routes/index.rst

+``lso.routes``
+==============
+
+.. automodule:: lso.routes
+   :members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   default
+   ip_trunk
+   router

docs/source/module/routes/ip_trunk.rst

+``lso.routes.ip_trunk``
+=======================
+
+.. automodule:: lso.routes.ip_trunk
+   :members:
+   :show-inheritance:

docs/source/module/routes/router.rst

+``lso.routes.router``
+======================
+
+.. automodule:: lso.routes.router
+   :members:
+   :show-inheritance:

docs/source/modules.rst

+=========================
+Sub-packages and -modules
+=========================
+
+This page lists references to the documentation of all sub-packages and -modules.
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   module/routes/index
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   module/config
+   module/playbook
+
+
+==========
+
+.. automodule:: lso
+   :members:
+   :show-inheritance:

docs/source/quickstart.rst

 Quick start
-==================
+===========
 
-*This is a quick setup guide for running standalone on your local machine*
+This is a quick setup guide for running standalone on your local machine.
 
 Install the module
---------------------
+------------------
 
 *One of these should be what you're looking for:*
 
@@ -32,11 +32,11 @@ Install the module
     pip install -r requirements.txt
 
 Running the app
--------------------
+---------------
 
-* Create a settings file, see `config.json.example` for an example.
-* If necessary, set the environment vairable `ANSIBLE_HOME` to a custom path.
-* Run the app like this (`app.py` starts the server on port 44444):
+* Create a settings file, see ``config.json.example`` for an example.
+* If necessary, set the environment variable ``ANSIBLE_HOME`` to a custom path.
+* Run the app like this (``app.py`` starts the server on port 44444):
 
   .. code-block:: bash