Documentation: Improve process for MkDocs-based documentation#129
Merged
Conversation
Get's rid of the following DeprecationWarning: 'uslugify' is deprecated. 'uslugify' is deprecated in favor of the configurable 'slugify' function. See documentation for more info. The configuration of 'slugify' is borrowed from PyMdown Extensions FAQ: https://facelessuser.github.io/pymdown-extensions/faq/#function-references-in-yaml The Python-Markdown 'toc' (Table of Contents) extension is documented at: https://python-markdown.github.io/extensions/toc/
The 'watch' configuration option is a global config https://www.mkdocs.org/user-guide/configuration/#watch not configuration of 'mkdocstrings' plugin (even though we want to watch 'src/' to automatically re-run mkdocstrings)'.
The 'start' and 'end' options define delimiters that marks the beginning and end of the contents to include, _not_ delimiters that will be put around included contents. Use 'include' instead of 'include-markdown', because the file being included is Python code, not Markdown document.
Using README.md files to create basis of the MkDocs-based project documentation with the help of mkdocs-include-markdown-plugin has one disadvantage: links to other READMEs and other files from those README.md files work for them when browsed on GitHub, but lead to 404 within the generated documentation. The 'rewrite-relative-urls' option helps, but is not a panacea. For example, notebooks/README.md file contains link to main README.md. This gets turned into ../README.md when include-markdown in notebooks.md gets processed. This needs to be adjusted to point to index.md (which includes README.md). Those README.md files also contain links to directories and non-Markdown files. Those needs to be turned in full GitHub URLs to directory (tree) or file (blob) in question. . There is 'mkdocs-redirects' plugin to create page redirects, but it is about actually creating a new page where an old page was that redirects to the new page using JavaScript redirect. It is intended for moved and renamed pages, rather than for fixing links. https://github.com/mkdocs/mkdocs-redirects Therefore a MkDocs hook was created, hooking `on_page_markdown` event, and doing search and replace on links (using regular expressions). The script with the hook is currently at scripts/my_hooks.py. https://www.mkdocs.org/user-guide/configuration/#hooks https://www.mkdocs.org/dev-guide/plugins/#on_page_markdown While at it, the hook also checks for non HTTPS external links.
jnareb
added
documentation
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Fix a few warnings from
mkdocs build/mkdocs serve, namely the use of deprecated 'uslugify' instead of configurable 'slugify', and 'watch' configuration added under 'mkdocstrings' plugin instead of being (as it should) a global option for mkdocs itself.Fix 'include-markdown' directive in
annotation_process.md(also replacing it with 'include' directive), so that example line callback function is included properly, inside code block.Rewrite links in included (via 'include-markdown') README.md Markdown files with custom hook, so that they lead either to documentation page, or to rendering of a file in question in project's GitHub.
While at it, replace HTTP links with HTTPS ones, where possible.