jrichardson / infra-docs

Forked from infra-docs 2 years ago
Clone

Fedora Infrastructure Documentation

Documentation Status on Read the Docs

This repository documents standard operating procedures for applications Fedora Infrastructure deploys and covers application development best practices for those applications we maintain ourselves.

This is designed to be consumed as a Sphinx documentation project. Documentation is available online on Pagure and on Read the Docs.

Contributing

This project is maintained on our Pagure repository. Contributions are reviewed and accepted by submitting a pull request to our Pagure repository. If you're not familiar with the pull request workflow, check out the Pagure documentation on pull requests.

Documentation is written in reStructedText. See Sphinx's reStructuredText Primer for a brief introduction to the concepts and format.

Local Builds

To build the documentation locally, create a virtualenv and install the requirements:

$ sudo dnf install python-virtualenvwrapper
$ mkvirtualenv -a $(pwd) infra-docs
$ pip install -r requirements.txt

Then build the documentation and open it in a browser of your choice:

$ cd docs
$ make html
$ firefox _build/html/index.html

Use SPHINXOPTS variable to pass build arguments to Sphinx. For example to recheck sources for warnings:

$ make html SPHINXOPTS="-n -E"

To leave the virtual environment:

$ deactivate

Finally, when you want to work on the documentation, you can re-enter the virtual environment with:

$ workon infra-docs

It will automatically change the current working directory to the repository root.