The docs for rules_testing are generated using a combination of Sphinx, Bazel, and Readthedocs.org. The Markdown files in source control are unlikely to render properly without the Sphinx processing step because they rely on Sphinx and MyST-specific Markdown functionalit.
The actual sources that Sphinx consumes are in the docs/source directory.
Manually building the docs isn't necessary -- readthedocs.org will automatically build and deploy them when commits are pushed to the repo.
To generate docs for development/preview purposes, install ibazel[^ibazel] and run:
ibazel run //docs:run_sphinx_build
This will build the docs and start a local webserver at http://localhost:8000 where you can view the output. As you edit files, ibazel will detect the file changes and re-run the build process, and you can simply refresh your browser to see the changes.
Sphinx is configured to parse Markdown files using MyST, which is a more advanced flavor of Markdown that supports most features of restructured text and integrates with Sphinx functionality such as automatic cross references, creating indexes, and using concise markup to generate rich documentation.
MyST features and behaviors are controlled by the Sphinx configuration file, docs/source/conf.py
. For more info, see https://myst-parser.readthedocs.io.
The Sphinx-specific configuration files and input doc files live in docs/source -- anything under this directory will be treated by Sphinx as something it should create documentation for.
The Sphinx configuration is docs/source/conf.py
. See https://www.sphinx-doc.org/ for details about the configuration file.
There's two basic parts to the readthedocs configuration:
.readthedocs.yaml
: This configuration file controls most settings, such as the OS version used to build, Python version, dependencies, what Bazel commands to run, etc.For more readthedocs configuration details, see docs.readthedocs.io.
Of particular note, //docs:requirements.txt
is used by readthedocs for specifying Python dependencies (including Sphinx version).
[^ibazel]: Quick install: npm install -g @bazel/ibazel