diff --git a/.gitignore b/.gitignore index eeed7fdb861c9a28233ccd309eab5a9ab5060142..9df71ef52ead788553d90c771678432f2fc33db0 100644 --- a/.gitignore +++ b/.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 diff --git a/build-docs.sh b/build-docs.sh index 7f50cd17d269d117e327707174395833ee4af4ac..51ebd8288614565bb80a6ef24e1a3407fb27ce82 100755 --- a/build-docs.sh +++ b/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 diff --git a/docs/.gitlab-ci.yml b/docs/.gitlab-ci.yml index 3278754ac84c323c264de032243fa24a968e9871..8df93e5d182093000c643012a07ba817c3b5afd2 100644 --- a/docs/.gitlab-ci.yml +++ b/docs/.gitlab-ci.yml @@ -1,24 +1,4 @@ --- -##### 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 diff --git a/docs/source/conf.py b/docs/source/conf.py index fdc60eb1938541b2d92963cfee0f8ad7cc7c2740..645bdfea854b6ce8886333e0a6a1805b94cc5087 100644 --- a/docs/source/conf.py +++ b/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' diff --git a/docs/source/index.rst b/docs/source/index.rst index 1a75263c41a5e8e3925d4413f5bb2d8928f8e8f4..3732b95b005e234b97ace16d5222488bbf7b78a1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,4 +1,4 @@ -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>`_ diff --git a/docs/source/module/config.rst b/docs/source/module/config.rst new file mode 100644 index 0000000000000000000000000000000000000000..feabe0956cb0994ff2dfcb1d29eb830fdce52271 --- /dev/null +++ b/docs/source/module/config.rst @@ -0,0 +1,6 @@ +``lso.config`` +============== + +.. automodule:: lso.config + :members: + :show-inheritance: diff --git a/docs/source/module/playbook.rst b/docs/source/module/playbook.rst new file mode 100644 index 0000000000000000000000000000000000000000..1219c80e8b18f134f91fe40b723469b713506f7e --- /dev/null +++ b/docs/source/module/playbook.rst @@ -0,0 +1,6 @@ +``lso.playbook`` +================ + +.. automodule:: lso.playbook + :members: + :show-inheritance: diff --git a/docs/source/module/routes/default.rst b/docs/source/module/routes/default.rst new file mode 100644 index 0000000000000000000000000000000000000000..af64afb2b28c16f46075ee3ba8bffe10749abd9d --- /dev/null +++ b/docs/source/module/routes/default.rst @@ -0,0 +1,6 @@ +``lso.routes.default`` +====================== + +.. automodule:: lso.routes.default + :members: + :show-inheritance: diff --git a/docs/source/module/routes/index.rst b/docs/source/module/routes/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..5adfbe1c6cb099b483d972cb274019b3aa3a7ab3 --- /dev/null +++ b/docs/source/module/routes/index.rst @@ -0,0 +1,17 @@ +``lso.routes`` +============== + +.. automodule:: lso.routes + :members: + :show-inheritance: + +Submodules +---------- + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + default + ip_trunk + router diff --git a/docs/source/module/routes/ip_trunk.rst b/docs/source/module/routes/ip_trunk.rst new file mode 100644 index 0000000000000000000000000000000000000000..c6c2e88566e4488e5720cbd2a9e87e85ef57c342 --- /dev/null +++ b/docs/source/module/routes/ip_trunk.rst @@ -0,0 +1,6 @@ +``lso.routes.ip_trunk`` +======================= + +.. automodule:: lso.routes.ip_trunk + :members: + :show-inheritance: diff --git a/docs/source/module/routes/router.rst b/docs/source/module/routes/router.rst new file mode 100644 index 0000000000000000000000000000000000000000..2f10a490b0f79bd255bd3b198e1fcbe5de362b03 --- /dev/null +++ b/docs/source/module/routes/router.rst @@ -0,0 +1,6 @@ +``lso.routes.router`` +====================== + +.. automodule:: lso.routes.router + :members: + :show-inheritance: diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000000000000000000000000000000000000..1455bfc7dbfb42a7ab16c31c913ccc497b334b48 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,31 @@ +========================= +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: diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 9d8f2dbc0319c57c50402428cec08f05782e9312..f906ccbaae06a10b42025c9aa6dc70f732fd1f33 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -1,10 +1,10 @@ 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