From c0bc8d86a006975a0e6550ab4182ca7c0f6deed7 Mon Sep 17 00:00:00 2001
From: Karel van Klink <karel.vanklink@geant.org>
Date: Tue, 4 Jul 2023 15:41:18 +0200
Subject: [PATCH] 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 | 1 -
README.md | 64 ++-----------------
docs/.gitlab-ci.yml | 8 +--
docs/build_docs.sh | 10 +++
docs/index.md | 32 ----------
docs/{ => source}/Makefile | 2 +-
docs/source/apidocs/.gitignore | 1 +
docs/{ => source}/conf.py | 17 ++++-
docs/{ => source}/glossary.md | 0
docs/source/index.md | 13 ++++
docs/source/quickstart.md | 62 ++++++++++++++++++
docs/{ => source}/static/custom.css | 0
docs/{ => source}/static/geant_logo_white.svg | 0
docs/test_documentation.sh | 10 ---
docs/vale/styles/Vocab/Sphinx/accept.txt | 2 +
15 files changed, 113 insertions(+), 109 deletions(-)
create mode 100755 docs/build_docs.sh
delete mode 100644 docs/index.md
rename docs/{ => source}/Makefile (96%)
create mode 100644 docs/source/apidocs/.gitignore
rename docs/{ => source}/conf.py (69%)
rename docs/{ => source}/glossary.md (100%)
create mode 100644 docs/source/index.md
create mode 100644 docs/source/quickstart.md
rename docs/{ => source}/static/custom.css (100%)
rename docs/{ => source}/static/geant_logo_white.svg (100%)
delete mode 100755 docs/test_documentation.sh
diff --git a/.gitignore b/.gitignore
index d30389c7..0831a3be 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,4 +14,3 @@ oss-params.json
docs/build
docs/vale/styles/*
!docs/vale/styles/Vocab/
-docs/source/modules
diff --git a/README.md b/README.md
index af580f00..146c051f 100644
--- a/README.md
+++ b/README.md
@@ -1,61 +1,5 @@
-## 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).
diff --git a/docs/.gitlab-ci.yml b/docs/.gitlab-ci.yml
index 5ef0839a..21c42d75 100644
--- a/docs/.gitlab-ci.yml
+++ b/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:
diff --git a/docs/build_docs.sh b/docs/build_docs.sh
new file mode 100755
index 00000000..11baf7ab
--- /dev/null
+++ b/docs/build_docs.sh
@@ -0,0 +1,10 @@
+#!/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/
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index d63b6e23..00000000
--- a/docs/index.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# GÉANT Service Orchestrator ({term}`GSO`)
-
-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
-glossary.md
-```
diff --git a/docs/Makefile b/docs/source/Makefile
similarity index 96%
rename from docs/Makefile
rename to docs/source/Makefile
index ed880990..43276bb9 100644
--- a/docs/Makefile
+++ b/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:
diff --git a/docs/source/apidocs/.gitignore b/docs/source/apidocs/.gitignore
new file mode 100644
index 00000000..72e8ffc0
--- /dev/null
+++ b/docs/source/apidocs/.gitignore
@@ -0,0 +1 @@
+*
diff --git a/docs/conf.py b/docs/source/conf.py
similarity index 69%
rename from docs/conf.py
rename to docs/source/conf.py
index c1ad4dc9..f82028fa 100644
--- a/docs/conf.py
+++ b/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
+
diff --git a/docs/glossary.md b/docs/source/glossary.md
similarity index 100%
rename from docs/glossary.md
rename to docs/source/glossary.md
diff --git a/docs/source/index.md b/docs/source/index.md
new file mode 100644
index 00000000..8ed5ec92
--- /dev/null
+++ b/docs/source/index.md
@@ -0,0 +1,13 @@
+# GÉANT Service Orchestrator ({term}`GSO`)
+
+Welcome to the documentation of the GÉANT Service Orchestrator, or {term}`GSO` for short.
+
+This documentation has the following sections:
+
+```{toctree}
+:caption: Contents
+:maxdepth: 1
+quickstart.md
+apidocs/gso/gso
+glossary.md
+```
diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md
new file mode 100644
index 00000000..1ddae9ef
--- /dev/null
+++ b/docs/source/quickstart.md
@@ -0,0 +1,62 @@
+# 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'``
diff --git a/docs/static/custom.css b/docs/source/static/custom.css
similarity index 100%
rename from docs/static/custom.css
rename to docs/source/static/custom.css
diff --git a/docs/static/geant_logo_white.svg b/docs/source/static/geant_logo_white.svg
similarity index 100%
rename from docs/static/geant_logo_white.svg
rename to docs/source/static/geant_logo_white.svg
diff --git a/docs/test_documentation.sh b/docs/test_documentation.sh
deleted file mode 100755
index dcb80d78..00000000
--- a/docs/test_documentation.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/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/
diff --git a/docs/vale/styles/Vocab/Sphinx/accept.txt b/docs/vale/styles/Vocab/Sphinx/accept.txt
index 1c26bb26..2fbf4392 100644
--- a/docs/vale/styles/Vocab/Sphinx/accept.txt
+++ b/docs/vale/styles/Vocab/Sphinx/accept.txt
@@ -1 +1,3 @@
toctree
+[Ss]ubpackages
+virtualenv
--
GitLab