docs: make readthedocs render a bit nicer and port docs over to Sphinx#1511
Merged
docs: make readthedocs render a bit nicer and port docs over to Sphinx#1511
Conversation
…Sphinx This makes the Sphinx-based docs hosted on readthedocs render a bit more nicely, fixes a few issues, and adds some features to //sphinxdocs Doc fixes/improvements: * Ports various docs over to Sphinx pages. They're split out from the readme file. * Version RTD is building is reflected in the docs * Fixes some references to github files * Includes the custom CSS file that styled the api docs * Removes `-Q` from doc building; all warnings should be fixed now * Added Bazel inventory file. Bazel doesn't provide one, but we can manually provide on and still use intersphinx functionality. * Added `gh-path` custom role. This is a shortcut for writing the whole github URL. * Sets the primary domain to None. The default is py, which we don't use much of, so it just results in confusing crossref errors. * Enable nitpicky mode to catch more errors. * Remove the `starlark` marker from codeblocks; that name isn't recognized by Sphinx. The highlighting is still sufficient. * Adds a glossary Sphinxdocs improvements: * Added a flag to pass along arbitrary `-D` args to the Sphinx invocations. This allows e.g., the `version` setting of the docs to be set on the command line from the `READTHEDOCS_VERSION` environment variable * Added inventory file generation. These are files that allow referencing external projects using intersphinx. * `sphinx_stardocs` have their public load path set as their page title. This groups the API docs more naturally by file. The path can be customized. * `sphinx_stardocs` can have a footer specified for generated pages. This allows easily added a list of link labels for easy re-use. * `readthedocs_install` now tries harder to find an open port * The conf.py file is moved into the generated sources directly. This was done because some config settings are relative to the conf.py file, which was being placed one directory above the regular sources.
Collaborator
Author
|
This can be previewed at: https://rules-python.readthedocs.io/en/latest/ |
aignas
approved these changes
Oct 19, 2023
add --config=rtd with --stamp linkify some urls include manual console script binary docs in generated api docs organize conf file by extension setting mark starlark a recognized lexer for codeblocks a few cleanups in the docs
…on into rtd-testing
Collaborator
Author
|
Hm, you know, I think i'll just delete the old stuff in docs/ in this PR, too. That'll avoid any odd rendering issues with myst-markdown in the bzl code, and fix the issue with bazel's downstream testing. I'll make sure to copy over any of the manual merging like what py_console_script_binary was doing |
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
2 participants
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 makes the Sphinx-based docs hosted on readthedocs render a bit more nicely, fixes a few issues, and adds some features to //sphinxdocs
This also moves all the docs onto Sphinx, deleting the checked-in documentation.
Doc fixes/improvements:
-Qfrom doc building; all warnings should be fixed nowand still use intersphinx functionality.
gh-pathcustom role. This is a shortcut for writing the whole github URL.just results in confusing crossref errors.
starlarkmarker from codeblocks; that name isn't recognized by Sphinx.The highlighting is still sufficient.
Sphinxdocs improvements:
-Dargs to the Sphinx invocations. This allowse.g., the
versionsetting of the docs to be set on the command line from theREADTHEDOCS_VERSIONenvironment variableprojects using intersphinx.
sphinx_stardocshave their public load path set as their page title. This groups theAPI docs more naturally by file. The path can be customized.
sphinx_stardocscan have a footer specified for generated pages. This allows easilyadded a list of link labels for easy re-use.
readthedocs_installnow tries harder to find an open portconfig settings are relative to the conf.py file, which was being placed one directory
above the regular sources.
Fixes #1484, #1481