Transition to Mkdocs for versioned api-docs #336
Conversation
|
CUrrently only a draft because I want to remove --push from the default .sh script and because i need to still verify that all dependencies are included in the pyproject.toml file. Unfortunately the changes inside the yml are not tested for functionality, we will have to see what happens during release or just try doing a testrun. Feel free to check out docs produced here: http://apidocs.zenml.io/0.5.7/ |
|
Will take a look Alexej! Could you change the name of the PR to something more verbose? I think that would make it clearer in the release notes! :) |
…, mkdocs-awesome-pages and mike
6dccf4c to
cb8a033
Compare
There was a problem hiding this comment.
I jut noticed one mistake. Other than that, i think we should test the deployment in a test run somewhere soon and remove the push also as you suggest.
Btw I notice that https://apidocs.zenml.io/ redirects to https://apidocs.zenml.io/latest which is currently down. I have changed the 0.5.7 docs to go directly to https://apidocs.zenml.io/0.5.7/ for now but we should fix this asap
docs/mkdocstrings_helper.py
Outdated
| ignored_modules: List[str], | ||
| sources_path: Path, | ||
| ) -> None: | ||
| # TODO [MED]: Find Solution for issue with click-decorated functions |
There was a problem hiding this comment.
Wrong TODO format -> Should be MEDIUM
Currently testing this |
|
I ran tests on two separate branches to verify different versions are pushed subsequently to the equivalent of gh-pages for the github actions. First this action was executed: https://github.com/zenml-io/zenml/runs/4925657388?check_suite_focus=true Then this one: https://github.com/zenml-io/zenml/runs/4925797327?check_suite_focus=true Here you can see the expected two versions (branch names): https://github.com/zenml-io/zenml/tree/misc/test_docs
|
| ignored_modules: List[str], | ||
| sources_path: Path, | ||
| ) -> None: | ||
| # TODO [MEDIUM]: Find Solution for issue with click-decorated functions |
There was a problem hiding this comment.
One quick comment: The todo parsing is currently only run in the src and tests directory, so this will not get detected
There was a problem hiding this comment.
Ah, good to know, I'll create a ticket manually for this
There was a problem hiding this comment.
unless you just want to add the docs to the todo parser, if you think that's worthwhile I don't see why not, it only includes .py files anyway
There was a problem hiding this comment.
something worth considering for the future
|
Is this good to go? |
Pre-requisites
Please ensure you have done the following:
Types of changes
Describe changes
Dynamically create docstrings when docs are served. Try it out locally by running docs/mkdocstrings_helper.py and then mkdocs serve from within the docs folder.