1# rules_python Sphinx docs generation 2 3The docs for rules_python 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 functionality. 7 8The actual sources that Sphinx consumes are in this directory, with Stardoc 9generating additional sources or Sphinx. 10 11Manually building the docs isn't necessary -- readthedocs.org will 12automatically build and deploy them when commits are pushed to the repo. 13 14## Generating docs for development 15 16Generating docs for development is a two-part process: starting a local HTTP 17server to serve the generated HTML, and re-generating the HTML when sources 18change. The quick start is: 19 20``` 21bazel run //docs:docs.serve # Run in separate terminal 22ibazel build //docs:docs # Automatically rebuilds docs 23``` 24 25This will build the docs and start a local webserver at http://localhost:8000 26where you can view the output. As you edit files, ibazel will detect the file 27changes and re-run the build process, and you can simply refresh your browser to 28see the changes. Using ibazel is not required; you can manually run the 29equivalent bazel command if desired. 30 31### Installing ibazel 32 33The `ibazel` tool can be used to automatically rebuild the docs as you 34development them. See the [ibazel docs](https://github.com/bazelbuild/bazel-watcher) for 35how to install it. The quick start for linux is: 36 37``` 38sudo apt install npm 39sudo npm install -g @bazel/ibazel 40``` 41 42## MyST Markdown flavor 43 44Sphinx is configured to parse Markdown files using MyST, which is a more 45advanced flavor of Markdown that supports most features of restructured text and 46integrates with Sphinx functionality such as automatic cross references, 47creating indexes, and using concise markup to generate rich documentation. 48 49MyST features and behaviors are controlled by the Sphinx configuration file, 50`docs/conf.py`. For more info, see https://myst-parser.readthedocs.io. 51 52## Sphinx configuration 53 54The Sphinx-specific configuration files and input doc files live in 55docs/. 56 57The Sphinx configuration is `docs/conf.py`. See 58https://www.sphinx-doc.org/ for details about the configuration file. 59 60## Readthedocs configuration 61 62There's two basic parts to the readthedocs configuration: 63 64* `.readthedocs.yaml`: This configuration file controls most settings, such as 65 the OS version used to build, Python version, dependencies, what Bazel 66 commands to run, etc. 67* https://readthedocs.org/projects/rules-python: This is the project 68 administration page. While most settings come from the config file, this 69 controls additional settings such as permissions, what versions are 70 published, when to publish changes, etc. 71 72For more readthedocs configuration details, see docs.readthedocs.io. 73