How to Write Documentation

How to Write Documentation#

The documentation uses the MyST markup language and renders to Sphinx as HTML, PDF or EPUB documents.

To build the documentation locally, from the root directory of the repository create a conda environment with

conda env create -y -f conda.yaml

This only needs to be done once. To activate this environment, use

conda activate pals

This needs to be done with any new window.

Then, compile the documentation with

HTML

make html

PDF

make latexpdf

Open the file build/html/index.html with your web browser to visualize. You are now ready to edit the markdown files that compose the documentation!

If you like to atuomatically rebuild changes on save of edited files, run in your particle-accelerator-lattice-standard directory:

sphinx-autobuild source/ build/html

and open the URL shown in the terminal, usually http://127.0.0.1:8000.

If you add new markdown files, do not forget to add them to the table of contents defined source/index.md. Finally, once you are happy with your changes, do not forget to commit and push them to your branch and open a pull request on GitHub.