Move to mkdocs #346
Draft
Move to mkdocs #346
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ItsDrike
added
a: documentation
ItsDrike
force-pushed
the
mkdocs
branch
6 times, most recently
from
f9597f3 to
8288c8f
Compare
|
ItsDrike
force-pushed
the
mkdocs
branch
17 times, most recently
from
cf79918 to
e665de7
Compare
ItsDrike
force-pushed
the
mkdocs
branch
2 times, most recently
from
557b7a8 to
0a8188c
Compare
This downgrade is necessary to get rid of a deprecation warning produced by mkdocstrings-python-xref. For more info, see: analog-garage/mkdocstrings-python-xref#29
py-mine-ci-bot
bot
added
the
s: stale
py-mine-ci-bot
bot
removed
the
s: stale
The original workflow somewhat naively ran deploy and always tried to push the built docs to the repo pages, which is however very unsafe to do from forks, not to mention that it wouldn't work anyways, since write access & secrets aren't available when the workflow is ran from forks on the `pull_request` trigger. It is a little annoying that we can't safely show the docs preview page for fork PRs, but it's the only safe way to go about this, and the docs building will still occur, to make sure that the building doesn't fail.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This removes Sphinx in favor of mkdocs for the project documentation.
Mkdocs is a major improvement on Sphinx, bringing us modern looking UI and markdown-based documentation source (rather than rst based with sphinx). The mkdocs syntax is much easier to follow and their usage documentation is a lot more user-friendly, making it generally much easier to write new documentation.
This PR doesn't just move the existing documentation over to mkdocs, rather, it's pretty much a complete rewrite, introducing a lot of new content and greatly modifying almost all of the old pages. This PR fully completes the project documentation task (#19).
Warning
Python docstrings originally written for Sphinx aren't entirely compatible with mkdocs. Even though some basic sphinx formatting is supported a lot of the things aren't and mkdocs is better suited for different docstring formats, like the google or numpy formats, with additional formatting being just the mkdocs markdown. Instead of going with a limiting sphinx format with a weird mix of rst & markdown, I've decided to abandon the sphinx format in favor of Google docstring format.
This almost certainly means that this will break any other PRs (well, at least those that did any modifications to docstrings in code). Of course, PRs that made modifications to the old docs will also need to be fixed.
CHANGELOG.mdfile in the docs