From 3a0bd23622021db14d94882bad57589b5e6bc4c6 Mon Sep 17 00:00:00 2001
From: Karel van Klink <karel.vanklink@geant.org>
Date: Thu, 5 Oct 2023 16:24:06 +0200
Subject: [PATCH] update documentation, add rst files, build step in pipeline
is not needed anymore
---
.gitignore | 5 -----
build-docs.sh | 1 -
docs/.gitlab-ci.yml | 23 +------------------
docs/source/conf.py | 3 +--
docs/source/index.rst | 6 ++---
docs/source/module/config.rst | 6 +++++
docs/source/module/playbook.rst | 6 +++++
docs/source/module/routes/default.rst | 6 +++++
docs/source/module/routes/index.rst | 17 ++++++++++++++
docs/source/module/routes/ip_trunk.rst | 6 +++++
docs/source/module/routes/router.rst | 6 +++++
docs/source/modules.rst | 31 ++++++++++++++++++++++++++
docs/source/quickstart.rst | 14 ++++++------
13 files changed, 90 insertions(+), 40 deletions(-)
create mode 100644 docs/source/module/config.rst
create mode 100644 docs/source/module/playbook.rst
create mode 100644 docs/source/module/routes/default.rst
create mode 100644 docs/source/module/routes/index.rst
create mode 100644 docs/source/module/routes/ip_trunk.rst
create mode 100644 docs/source/module/routes/router.rst
create mode 100644 docs/source/modules.rst
diff --git a/.gitignore b/.gitignore
index eeed7fd..9df71ef 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 7f50cd1..51ebd82 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 3278754..8df93e5 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 fdc60eb..645bdfe 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 1a75263..3732b95 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 0000000..feabe09
--- /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 0000000..1219c80
--- /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 0000000..af64afb
--- /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 0000000..5adfbe1
--- /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 0000000..c6c2e88
--- /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 0000000..2f10a49
--- /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 0000000..1455bfc
--- /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 9d8f2db..f906ccb 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
--
GitLab