Writing Documentation

This section explains how to write PanDA documentation. If you just want to add changes to existing documentation see Adding Changes to Documentation.

1. Preparation

First, you need to install sphinx packages

pip install sphinx sphinx-rtd-theme sphinx-prompt nbsphinx sphinx_tabs

and pandoc . Then fork the main or dev branch of the panda-docs repository following GitHub HowTo .

2. Repository structure

You can see the following structure in the repository.

/panda-docs
    ├── /docs
       ├── /build
       ├── make.bat
       ├── Makefile
       └── /source
          ├── conf.py
          ├── index.rst
          ├── /images
          ├── /_static
          └── /section_name
              ├── section_name.rst
              ├── subsection_name.rst
              └── ...

You edit or add RST files under the source directory or sub-directories in the source directory. index.rst is the RST file for the main page, and conf.py controls how sphinx builds documents. There is a sub-directory for each section in the source directory. Each section is composed of one main RST file with the section name plus .rst extension and other RST files for subsections.

3. Build documents

Once you edit some RST files you need to build documents.

cd panda-docs/docs
make html

This will build html documents in the build directory. You can check how documents look like by opening panda-docs/docs/build/html/index.html via your web browser.

4. Submitting pull requests

Once you are comfortable with the changes, you should push them to your forked repository and submit a pull request following the github doc . Then requests are reviewed, and the changes will be merged to the main branch once approved.

5. Publish the latest documents

Actions on the git repository such as push and tagging trigger automatic-builds on the Read The Docs. The latest (main) and dev documents show up at https://panda-wms.readthedocs.io/en/latest/ and https://panda-wms.readthedocs.io/en/dev/ respectively.