docs(python-sdk): generate documentation and api reference with mkdocs

[Lasse-numerous]

Changing docs to use mkdocs and mkdocstrings

[jfeodor]

Can you rename the PR so it matches the semantic commits naming conventions?

For example: docs(python-sdk): generate documentation and api reference with `mkdocs`

[jfeodor]

The version of mkdocstrings or mkdocstrings-python seems to be incorrect. I think it should be:
mkdocstrings==0.26.2 and mkdocstrings-python==1.12.2.

Also a configuration error is displayed.

WARNING -  Config value 'plugins': Plugin 'mkdocstrings' option 'rendering': Unrecognised configuration name: rendering

Details

If I install new dependencies that are specified I get an error:

(venv) feo@jnielsen:~/numerous-sdk$ mkdocs serve
WARNING -  Config value 'plugins': Plugin 'mkdocstrings' option 'rendering': Unrecognised configuration name: rendering
INFO    -  Building documentation...
INFO    -  Cleaning site directory
ERROR   -  Error reading page 'collections.md': No module named 'griffe.collections'
Traceback (most recent call last):
  File "/home/feo/numerous-sdk/venv-fresh/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocs/__main__.py", line 268, in serve_command
    serve.serve(**kwargs)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 85, in serve
    builder(config)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 67, in builder
    build(config, serve_url=None if is_clean else serve_url, dirty=is_dirty)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocs/commands/build.py", line 310, in build
    _populate_page(file.page, config, files, dirty)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocs/commands/build.py", line 167, in _populate_page
    page.render(config, files)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocs/structure/pages.py", line 285, in render
    self.content = md.convert(self.markdown)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/markdown/core.py", line 357, in convert
    root = self.parser.parseDocument(self.lines).getroot()
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/markdown/blockparser.py", line 117, in parseDocument
    self.parseChunk(self.root, '\n'.join(lines))
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/markdown/blockparser.py", line 136, in parseChunk
    self.parseBlocks(parent, text.split('\n\n'))
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/markdown/blockparser.py", line 158, in parseBlocks
    if processor.run(parent, blocks) is not False:
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocstrings/extension.py", line 128, in run
    html, handler, data = self._process_block(identifier, block, heading_level)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocstrings/extension.py", line 199, in _process_block
    handler = self._handlers.get_handler(handler_name, handler_config)
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocstrings/handlers/base.py", line 460, in get_handler
    module = importlib.import_module(f"mkdocstrings_handlers.{name}")
  File "/usr/local/lib/python3.9/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1030, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1007, in _find_and_load
  File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 680, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 850, in exec_module
  File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocstrings_handlers/python/__init__.py", line 3, in <module>
    from mkdocstrings_handlers.python.handler import get_handler
  File "/home/feo/numerous-sdk/venv-fresh/lib/python3.9/site-packages/mkdocstrings_handlers/python/handler.py", line 14, in <module>
    from griffe.collections import LinesCollection, ModulesCollection
ModuleNotFoundError: No module named 'griffe.collections'

However, if I upgrade mkdocstrings-python, it works:

(venv) feo@jnielsen:~/numerous-sdk$ pip install -U mkdocstrings-python
Requirement already satisfied: mkdocstrings-python in ./venv-fresh/lib/python3.9/site-packages (1.10.0)
Collecting mkdocstrings-python
  Using cached mkdocstrings_python-1.12.2-py3-none-any.whl (111 kB)
Requirement already satisfied: mkdocs-autorefs>=1.2 in ./venv-fresh/lib/python3.9/site-packages (from mkdocstrings-python) (1.2.0)
Collecting mkdocstrings>=0.26
  Using cached mkdocstrings-0.26.2-py3-none-any.whl (29 kB)
Requirement already satisfied: griffe>=0.49 in ./venv-fresh/lib/python3.9/site-packages (from mkdocstrings-python) (1.5.1)
Requirement already satisfied: colorama>=0.4 in ./venv-fresh/lib/python3.9/site-packages (from griffe>=0.49->mkdocstrings-python) (0.4.6)
Requirement already satisfied: Markdown>=3.3 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs-autorefs>=1.2->mkdocstrings-python) (3.7)
Requirement already satisfied: markupsafe>=2.0.1 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs-autorefs>=1.2->mkdocstrings-python) (3.0.2)
Requirement already satisfied: mkdocs>=1.1 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs-autorefs>=1.2->mkdocstrings-python) (1.6.0)
Requirement already satisfied: Jinja2>=2.11.1 in ./venv-fresh/lib/python3.9/site-packages (from mkdocstrings>=0.26->mkdocstrings-python) (3.1.4)
Requirement already satisfied: platformdirs>=2.2 in ./venv-fresh/lib/python3.9/site-packages (from mkdocstrings>=0.26->mkdocstrings-python) (4.3.6)
Requirement already satisfied: importlib-metadata>=4.6 in ./venv-fresh/lib/python3.9/site-packages (from mkdocstrings>=0.26->mkdocstrings-python) (8.5.0)
Requirement already satisfied: pymdown-extensions>=6.3 in ./venv-fresh/lib/python3.9/site-packages (from mkdocstrings>=0.26->mkdocstrings-python) (10.11.2)
Requirement already satisfied: typing-extensions>=4.1 in ./venv-fresh/lib/python3.9/site-packages (from mkdocstrings>=0.26->mkdocstrings-python) (4.12.2)
Requirement already satisfied: click>=7.0 in ./venv-fresh/lib/python3.9/site-packages (from mkdocstrings>=0.26->mkdocstrings-python) (8.1.7)
Requirement already satisfied: zipp>=3.20 in ./venv-fresh/lib/python3.9/site-packages (from importlib-metadata>=4.6->mkdocstrings>=0.26->mkdocstrings-python) (3.20.2)
Requirement already satisfied: pathspec>=0.11.1 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs>=1.1->mkdocs-autorefs>=1.2->mkdocstrings-python) (0.12.1)
Requirement already satisfied: watchdog>=2.0 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs>=1.1->mkdocs-autorefs>=1.2->mkdocstrings-python) (5.0.3)
Requirement already satisfied: packaging>=20.5 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs>=1.1->mkdocs-autorefs>=1.2->mkdocstrings-python) (24.1)
Requirement already satisfied: pyyaml-env-tag>=0.1 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs>=1.1->mkdocs-autorefs>=1.2->mkdocstrings-python) (0.1)
Requirement already satisfied: ghp-import>=1.0 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs>=1.1->mkdocs-autorefs>=1.2->mkdocstrings-python) (2.1.0)
Requirement already satisfied: mergedeep>=1.3.4 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs>=1.1->mkdocs-autorefs>=1.2->mkdocstrings-python) (1.3.4)
Requirement already satisfied: pyyaml>=5.1 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs>=1.1->mkdocs-autorefs>=1.2->mkdocstrings-python) (6.0.2)
Requirement already satisfied: mkdocs-get-deps>=0.2.0 in ./venv-fresh/lib/python3.9/site-packages (from mkdocs>=1.1->mkdocs-autorefs>=1.2->mkdocstrings-python) (0.2.0)
Requirement already satisfied: python-dateutil>=2.8.1 in ./venv-fresh/lib/python3.9/site-packages (from ghp-import>=1.0->mkdocs>=1.1->mkdocs-autorefs>=1.2->mkdocstrings-python) (2.9.0.post0)
Requirement already satisfied: six>=1.5 in ./venv-fresh/lib/python3.9/site-packages (from python-dateutil>=2.8.1->ghp-import>=1.0->mkdocs>=1.1->mkdocs-autorefs>=1.2->mkdocstrings-python) (1.16.0)
Installing collected packages: mkdocstrings, mkdocstrings-python
  Attempting uninstall: mkdocstrings
    Found existing installation: mkdocstrings 0.25.0
    Uninstalling mkdocstrings-0.25.0:
      Successfully uninstalled mkdocstrings-0.25.0
  Attempting uninstall: mkdocstrings-python
    Found existing installation: mkdocstrings-python 1.10.0
    Uninstalling mkdocstrings-python-1.10.0:
      Successfully uninstalled mkdocstrings-python-1.10.0
Successfully installed mkdocstrings-0.26.2 mkdocstrings-python-1.12.2

[notice] A new release of pip is available: 23.0.1 -> 24.3.1
[notice] To update, run: pip install --upgrade pip
(venv) feo@jnielsen:~/numerous-sdk$ mkdocs serve
WARNING -  Config value 'plugins': Plugin 'mkdocstrings' option 'rendering': Unrecognised configuration name: rendering
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Doc file 'README.md' contains a link '#development-of-python-sdk-', but there is no such anchor on this page.
INFO    -  Documentation built in 0.34 seconds
INFO    -  [11:27:48] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [11:27:48] Serving on http://127.0.0.1:8000/

[jfeodor]

Looks good, apart from some details about dependency versions and a configuration error. See comments in the PR.

[Lasse-numerous]

@jfeodor I have made the requested changes.

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud