Update documentation

move readme to quickstart section in generated documentation
update build_docs.sh to work again
move from sphinx-apidoc to apidoc2 for MD support

.gitignore

@@ -14,4 +14,3 @@ oss-params.json
 docs/build
 docs/vale/styles/*
 !docs/vale/styles/Vocab/
-docs/source/modules

README.md

-## Environment and dependencies
+# GÉANT Service Orchestrator
+The GÉANT interpretation of [`orchestrator-core`](https://github.com/workfloworchestrator/orchestrator-core).
 
-- Install python 3.10 if you don't have it already:
-	- ``add-apt-repository ppa:deadsnakes/ppa``
-	- ``apt install python3.10 python3.10-distutils``
-- Follow Steps 1 and 2 from here to install dependencies and setup DB: https://workfloworchestrator.org/orchestrator-core/workshops/beginner/debian/
-- To install the orchestrator GUI, you can follow the steps 5 and 6 from the above link.
-- Create a virtualenv:
-	- ``source /usr/share/virtualenvwrapper/virtualenvwrapper.sh``
-	- ``mkvirtualenv --python python3.10 gso``
-- To use the virtualenv:
-	- `source /usr/share/virtualenvwrapper/virtualenvwrapper.sh`
-	- `workon gso`
-
-## Install
-
-Do all of this inside the virtualenv.
-- Clone this repo and ``cd`` into it
-- ``pip install -r requirements.txt`` 
-	- If you get an error because you pip version is too old, run this: `curl -sS https://bootstrap.pypa.io/get-pip.py | python3.10`
-- ``pip install -e .``
-- `cd` into `gso` directory and create ``oss-params.json`` based on the ``oss-params-example.json`` file.
-- Export the oss-params file: ``export OSS_PARAMS_FILENAME="/path/to/oss-params.json"``
-- Upgrade DB to latest revision: `PYTHONPATH=. python main.py db upgrade heads`
-
-## Run
-
-- The core of workflow orchestrator can be started with ``uvicorn --host 0.0.0.0 --port 8080 main:app`` from inside the ``gso`` directory of this repo.
-- The GUI can be started with ``yarn start``.
-
-
-## Useful WFO Resources
-
-- WFO API (Swagger): https://workfloworchestrator.org/orchestrator-core/architecture/application/api/
-- WFO API (repo): https://github.com/workfloworchestrator/orchestrator-core/tree/main/orchestrator/api/api_v1/endpoints
-- Carolina notes:
-https://wiki.geant.org/pages/viewpage.action?pageId=562921625
-
-### API examples
-
-*Note: update IP address in the request to your own where you're running WFO.*
-
-**Creating subscriptions** (look at initial_input_form_generator method of the workflow to find what properties need to be passed in the data of the POST request)
-
-Create process that produces a new subscription (CREATE workflow)
-
-``curl -X POST -H "Content-Type: application/json" http://10.98.1.62:8080/api/processes/create_trunk --data '[{"product": "321045fc-21ec-476b-b67b-5f211e47c3d7"},{"trunk_name": "mytrunkfromapi", "geant_s_sid": "a1b2c3"}]'``
-
-Create process that manipulates the state of a subscription (TERMINATE workflow)
-
-``curl -X POST -H "Content-Type: application/json" http://10.98.1.62:8080/api/processes/terminate_trunk --data '[{"subscription_id": "910e7044-c427-46d1-afc3-7817e221d45d"}, {"are_you_sure": "yes"}]'``
-
-**Deleting subscriptions** (not the same as running a TERMINATE workflow for a subscription, but to actually erase it from the WFO database)
-
-Delete a subscription:
-
-``curl -X 'DELETE' 'http://10.98.1.62:8080/api/subscriptions/3f16532b-0a48-4fe3-802a-36b3f54eed0e'``
-
-To do the above, you first have to delete the processes first:
-
-``curl -X 'DELETE' 'http://10.98.1.62:8080/api/processes/7447a3e9-7c58-4ae7-8804-c0a75c39c924'``
+## Documentation
+You can build the documentation locally using [build_docs.sh](docs/build_docs.sh).

docs/.gitlab-ci.yml

@@ -7,14 +7,14 @@ build-documentation:
   image: sphinxdoc/sphinx:latest
 
   before_script:
-    - pip install sphinx sphinx_rtd_theme myst-parser
+    - pip install sphinx_rtd_theme sphinx-autodoc2 myst-parser
+    - cd $CI_PROJECT_DIR/docs/source
   script:
-    - sphinx-apidoc gso gso/app.py -o docs/source
-    - sphinx-build -b html docs/source docs/build
+    - make html
 
   artifacts:
     paths:
-      - docs/build/html
+      - $CI_PROJECT_DIR/docs/build/html
 
 ##### Vale    - Documentation linter
 lint-documentation:

docs/build_docs.sh

+#!/bin/bash
+
+docker run -it --rm -v $(pwd)/../:/gso sphinxdoc/sphinx:latest /bin/bash -c \
+"pip install sphinx-autodoc2 sphinx_rtd_theme myst-parser;cd /gso/docs/source;make html"
+
+if [ ! -d ./vale/styles/proselint ] || [ ! -d ./vale/styles/Microsoft ]; then
+  docker run -it --rm -v $(pwd):/docs jdkato/vale:latest --config="/docs/vale/.vale.ini" sync
+fi
+
+docker run -it --rm -v $(pwd):/docs jdkato/vale:latest --config="/docs/vale/.vale.ini" /docs/build/html/_sources/

docs/Makefile → docs/source/Makefile

@@ -6,7 +6,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
-BUILDDIR      = build
+BUILDDIR      = ../build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/source/apidocs/.gitignore

+*

docs/conf.py → docs/source/conf.py

@@ -4,7 +4,7 @@ copyright = '2023, GÉANT Vereniging'
 author = 'GÉANT Orchestration and Automation Team'
 
 # -- General configuration ---------------------------------------------------
-extensions = ['sphinx_rtd_theme', 'myst_parser']
+extensions = ['sphinx_rtd_theme', 'myst_parser', 'autodoc2']
 
 templates_path = ['templates']
 exclude_patterns = ['build', 'Thumbs.db', '.DS_Store', 'venv', 'vale']
@@ -16,6 +16,12 @@ source_suffix = {
 myst_enable_extensions = ['attrs_block', 'deflist', 'replacements', 'smartquotes', 'strikethrough']
 suppress_warnings = ['myst.strikethrough']
 
+# -- Options for autodoc -----------------------------------------------------
+autodoc2_packages = [
+    "../../gso"
+]
+autodoc2_render_plugin = "myst"
+
 # -- Options for HTML output -------------------------------------------------
 html_theme = 'sphinx_rtd_theme'
 html_static_path = ['static']
@@ -24,3 +30,12 @@ html_theme_options = {
 }
 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.
+autoclass_content = 'both'
+autodoc_typehints = 'none'
+
+# Display todos by setting to True
+todo_include_todos = True
+

docs/index.md → docs/source/index.md

 # GÉANT Service Orchestrator ({term}`GSO`)
 
-Welcome to the documentation of the GÉANT Service Orchestrator, or {term}`GSO` for short. \
+Welcome to the documentation of the GÉANT Service Orchestrator, or {term}`GSO` for short.
 
 This documentation has the following sections:
 
 ```{toctree}
-:caption: Background
-:maxdepth: 2
-overview/index.md
-architecture/index.md
-```
-
-```{toctree}
-:caption: Modeling
-:maxdepth: 2
-modeling/index.md
-modeling/ports.md
-```
-
-```{toctree}
-:caption: Processes
-:maxdepth: 2
-processes/node_provisioning.md
-processes/deploy_router.md
-```
-
-```{toctree}
-:caption: —
-:maxdepth: 2
+:caption: Contents
+:maxdepth: 1
+quickstart.md
+apidocs/gso/gso
 glossary.md
 ```

docs/source/quickstart.md

+# Quickstart
+
+## Development environment and dependencies
+
+- Install python 3.10 if you don't have it already:
+	- ``add-apt-repository ppa:deadsnakes/ppa``
+	- ``apt install python3.10 python3.10-distutils``
+- Follow Steps 1 and 2 from here to install dependencies and setup DB: https://workfloworchestrator.org/orchestrator-core/workshops/beginner/debian/
+- To install the orchestrator GUI, you can follow the steps 5 and 6 from the above link.
+- Create a virtual environment:
+	- ``source /usr/share/virtualenvwrapper/virtualenvwrapper.sh``
+	- ``mkvirtualenv --python python3.10 gso``
+- To use the virtual environment:
+	- `source /usr/share/virtualenvwrapper/virtualenvwrapper.sh`
+	- `workon gso`
+
+## Installation
+
+Do all of this inside the virtual environment.
+- Clone this repository and ``cd`` into it
+- ``pip install -r requirements.txt`` 
+	- If you get an error because you pip version is too old, run this: `curl -sS https://bootstrap.pypa.io/get-pip.py | python3.10`
+- ``pip install -e .``
+- `cd` into `gso` directory and create ``oss-params.json`` based on the ``oss-params-example.json`` file.
+- Export the oss-params file: ``export OSS_PARAMS_FILENAME="/path/to/oss-params.json"``
+- Upgrade DB to latest revision: `PYTHONPATH=. python main.py db upgrade heads`
+
+## Run
+
+- The core of workflow orchestrator can be started with ``uvicorn --host 0.0.0.0 --port 8080 main:app`` from inside the ``gso`` directory of this repository.
+- The GUI can be started with ``yarn start``.
+
+
+## Useful WFO Resources
+
+- WFO API (Swagger): <https://workfloworchestrator.org/orchestrator-core/architecture/application/api/>
+- WFO API (repository): <https://github.com/workfloworchestrator/orchestrator-core/tree/main/orchestrator/api/api_v1/endpoints>
+- Carolina's notes: <https://wiki.geant.org/pages/viewpage.action?pageId=562921625>
+
+### API examples
+
+*Note: update IP address in the request to your own where you're running WFO.*
+
+**Creating subscriptions** (look at the `initial_input_form_generator` method of the workflow to find what properties need to be passed in the data of the POST request)
+
+Create process that produces a new subscription (CREATE workflow)
+
+``curl -X POST -H "Content-Type: application/json" http://10.98.1.62:8080/api/processes/create_trunk --data '[{"product": "321045fc-21ec-476b-b67b-5f211e47c3d7"},{"trunk_name": "mytrunkfromapi", "geant_s_sid": "a1b2c3"}]'``
+
+Create process that manipulates the state of a subscription (TERMINATE workflow)
+
+``curl -X POST -H "Content-Type: application/json" http://10.98.1.62:8080/api/processes/terminate_trunk --data '[{"subscription_id": "910e7044-c427-46d1-afc3-7817e221d45d"}, {"are_you_sure": "yes"}]'``
+
+**Deleting subscriptions** (not the same as running a TERMINATE workflow for a subscription, but to actually erase it from the WFO database)
+
+Delete a subscription:
+
+``curl -X 'DELETE' 'http://10.98.1.62:8080/api/subscriptions/3f16532b-0a48-4fe3-802a-36b3f54eed0e'``
+
+To do the above, you first have to delete the processes first:
+
+``curl -X 'DELETE' 'http://10.98.1.62:8080/api/processes/7447a3e9-7c58-4ae7-8804-c0a75c39c924'``

docs/test_documentation.sh

-#!/bin/bash
-
-docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx:latest /bin/bash -c \
-"pip install sphinx_rtd_theme myst-parser;cd docs;make html"
-
-if [ ! -d ./vale/styles/proselint ] || [ ! -d ./vale/styles/Microsoft ]; then
-  docker run -it --rm -v $(pwd):/gso jdkato/vale:latest --config="/gso/vale/.vale.ini" sync
-fi
-
-docker run -it --rm -v $(pwd):/gso jdkato/vale:latest --config="/gso/vale/.vale.ini" /gso/build/html/_sources/

docs/vale/styles/Vocab/Sphinx/accept.txt

 toctree
+[Ss]ubpackages
+virtualenv