2.1 KiB
Documentation
Documentation is built with Sphinx and authored in Markdown as much as possible. Markdown support for Sphinx is provided by MyST, which provides a number of extensions to the Markdown dialect you may be used to in order to take advantage of various Sphinx features.
Workflow
Building
The docs directory contains a Makefile (gh-file:pulumi#docs/Makefile) for
working with the documentation. Generally you'll just want:
make -C docs watch
which will watch for changes and rebuild the documentation as needed, serving the results at http://localhost:8000/docs/README.html.
Deployment
This documentation is deployed to Read the Docs as
part of our CI/CD pipelines. The build target in the Makefile is used to
build an HTML version of the documentation that Read the Docs then deploys. See
the gh-file:pulumi#.readthedocs.yaml configuration in the root of the
repository for more information.
Previewing changes
If you want to preview the documentation as it will appear on Read the Docs, simply raise a PR with your changes. Read the Docs will build your PR and generate a preview site for you to review. The link to the preview site will appear in the list of checks on your PR. See Read the Docs' documentation on preview builds for more.
Local builds
If you want to build the documentation without watching for changes, you can use
the build target yourself locally, too. Set the READTHEDOCS_OUTPUT
environment variable to the location you'd like the documentation to be built to
and then run the build:
export READTHEDOCS_OUTPUT=/path/to/output
make -C docs build
build will compile documentation to a static HTML website in the
/path/to/output/html directory; you can open the index.html file in your
browser to view the built files from there:
open /path/to/output/html/index.html
:::{toctree} :maxdepth: 1 :titlesonly:
/docs/writing /docs/diagrams :::