feat: v7 mkdocs #3287
feat: v7 mkdocs #3287
Conversation
* Start migrating the documentation from .rst sphynx to .md material for mkdocs. Add mkdocs.yml with proper configuration, enable automated generation of the doc API from the docstring, and start converting a few pages (index, getting started, developers) for demo. * Add automated (opt-in) tests of all python codeblocks in the markdown docs using pytest-markdown-docs. Needed to comment 1 small test that seemingly should fail (AttributeError: DefinedNamespace like object has no attribute '_NS', indeed the DefinedNamespace class expect a _NS, so it makes sense it fails) but for some reason it was not properly failing when ran with regular pytest, but it fails with pytest-markdown-docs * convert all documentations pages to markdown, convert all docstrings to markdown with google style, updated config for mkdocs (readthedocs, tox, task) fixed #3128 * delete files, dependencies and mentions related to sphinx * uncomment test previously commented for experimenting with markdown codeblock testing * update poetry lock * blacked again * ignore mypy errors --------- Co-authored-by: Vincent Emonet <vincent.emonet@gmail.com>
|
One thing to note: since we need to support python 3.9, we cannot install the latest major versions of the various mkdocs plugins. This results in some pages not generating all of the content from the python modules/scripts. For example, see the examples page in this PR: 
Compared to the examples page in 
I think it has something to do with the |
…he python constraint for mkdocs deps
|
I've noticed readthedocs uses python 3.13 to perform the doc builds. For some reason, I thought we were running the doc builds on the lowest supported python version. I've now fixed the above issue by updating the mkdocs dependencies to the latest with a python version constraint of |
|
To clarify the comment above, we now only run doc build test on python 3.11 in the validate workflow matrix. There's no point running the docs build on different python versions when readthedocs only uses the latest stable python version anyway. I've arbitrarily chosen 3.11 but readthedocs currently uses 3.13 for all builds. |
Summary of changes
This PR backports PR #3143 from
mainto v7.Checklist
the same change.
./examples.so maintainers can fix minor issues and keep your PR up to date.