1# rules_testing docs generation 2 3The docs for rules_testing are generated using a combination of Sphinx, Bazel, 4and Readthedocs.org. The Markdown files in source control are unlikely to render 5properly without the Sphinx processing step because they rely on Sphinx and 6MyST-specific Markdown functionalit. 7 8The actual sources that Sphinx consumes are in the docs/source directory. 9 10Manually building the docs isn't necessary -- readthedocs.org will 11automatically build and deploy them when commits are pushed to the repo. 12 13## Generating docs for development 14 15To generate docs for development/preview purposes, install 16[ibazel](https://github.com/bazelbuild/bazel-watcher)[^ibazel] and run: 17 18``` 19ibazel run //docs:run_sphinx_build 20``` 21 22This will build the docs and start a local webserver at http://localhost:8000 23where you can view the output. As you edit files, ibazel will detect the file 24changes and re-run the build process, and you can simply refresh your browser to 25see the changes. 26 27## MyST Markdown flavor 28 29Sphinx is configured to parse Markdown files using MyST, which is a more 30advanced flavor of Markdown that supports most features of restructured text and 31integrates with Sphinx functionality such as automatic cross references, 32creating indexes, and using concise markup to generate rich documentation. 33 34MyST features and behaviors are controlled by the Sphinx configuration file, 35`docs/source/conf.py`. For more info, see https://myst-parser.readthedocs.io. 36 37## Sphinx configuration 38 39The Sphinx-specific configuration files and input doc files live in 40docs/source -- anything under this directory will be treated by Sphinx as 41something it should create documentation for. 42 43The Sphinx configuration is `docs/source/conf.py`. See 44https://www.sphinx-doc.org/ for details about the configuration file. 45 46## Readthedocs configuration 47 48There's two basic parts to the readthedocs configuration: 49 50* `.readthedocs.yaml`: This configuration file controls most settings, such as 51 the OS version used to build, Python version, dependencies, what Bazel 52 commands to run, etc. 53* https://readthedocs.org/projects/rules-testing: This is the project 54 administration page. While most settings come from the config file, this 55 controls additional settings such as permissions, what versions are 56 published, when to publish changes, etc. 57 58For more readthedocs configuration details, see docs.readthedocs.io. 59 60Of particular note, `//docs:requirements.txt` is used by readthedocs for 61specifying Python dependencies (including Sphinx version). 62 63[^ibazel]: Quick install: `npm install -g @bazel/ibazel` 64