use mkdocstrings to generate API docs

[branfosj]

Uses:

• mkdocstrings
• mkdocs-gen-files
• mkdocs-literate-nav
• mkdocs-section-index

Based on the example at https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages.

This expects to find the easybuild framework checked out in src

• I.e. git clone git@github.com:easybuilders/easybuild-framework.git src

Issue:

• py2.py causes this to fail
  • I suspect that this tries to import the modules and fails on py2.py as we are using Python 3
  • This gets replaced during document generation

[boegel]

While playing with this, I hit the following error when building the docs with mkdocs build:

ERROR    -  Error reading page 'api/easybuild/index.md': 'easyconfigs'
Traceback (most recent call last):
  File "/Users/kehoste/Library/Python/3.9/lib/python/site-packages/griffe/loader.py", line 473, in _member_parent
    return module[parent_parts]
  File "/Users/kehoste/Library/Python/3.9/lib/python/site-packages/griffe/mixins.py", line 27, in __getitem__
    return self.members[parts[0]][parts[1:]]  # type: ignore[attr-defined]
KeyError: 'easyconfigs'

This is somehow caused by having all easybuild-* code repos (+ vsc-install and vsc-base) listed in my $PYTHONPATH:

$ echo $PYTHONPATH
/Users/kehoste/work/easybuild-easyconfigs:/Users/kehoste/work/easybuild-easyblocks:/Users/kehoste/work/easybuild-framework:/Users/kehoste/work/vsc-install/lib:/Users/kehoste/work/vsc-base/lib

Workaround is to just wipe $PYTHONPATH while running mkdocs build:

PYTHONPATH= mkdocs build

[boegel]

Maybe src/easybuild-framework makes more sense?

Eventually, it could be interesting to also have auto-generated API docs for easybuild.easyblocks, perhaps...

We can tackle this in a follow-up PR, where we also try to avoid that src must be populated in order for the documentation build to work, since this also requires changes to gen_ref_pages.py

[branfosj]

We can tackle that in a follow on to this

[boegel]

opened #88 to follow up on this