mirror of https://github.com/pulumi/pulumi.git
67 lines
2.1 KiB
Markdown
67 lines
2.1 KiB
Markdown
# Documentation
|
|
|
|
Documentation is built with [Sphinx](https://www.sphinx-doc.org) and authored in
|
|
Markdown as much as possible. Markdown support for Sphinx is provided by
|
|
[MyST](https://myst-parser.readthedocs.io), 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:
|
|
|
|
```sh
|
|
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](https://readthedocs.org) 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](https://docs.readthedocs.io/en/stable/pull-requests.html) 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
open /path/to/output/html/index.html
|
|
```
|
|
|
|
:::{toctree}
|
|
:maxdepth: 1
|
|
:titlesonly:
|
|
|
|
/docs/writing
|
|
/docs/diagrams
|
|
:::
|