Python Docs

Most of the Python documentation comes from Python-script-generated ∗.rst files. There are some statically written files. Be careful. The dynamically generated files should have a “WARNING” message at or near the top of the documents indicating that the file should not be edited directly.

This means “editing” one of those ∗.rst files is really editing the .py file (or chain of files) that created it.

All the script-generated documentation falls into two groups: API docs, and Example+Writeup docs.

API docs

Currently, all the API documents are built by this file:

\common\python\test\make_api_docs.py

Some main features of this file worth noting:

  • the first lines of the file are comments that describe its use — how to run the file, where its output is created, where to copy the output

  • it is set to output the files it creates to a folder named “doc” that is a sibling of the “test” folder that contains it

  • the files in the ‘doc’ folder that are output need to be copied manually into the correct location in the doc set where they will be used (and these will need to be committed in svn after the copy).

Example+Writeup Docs

The example docs are more complicated, because they are built per-code. Each of PFC, 3DEC, and FLAC3D will have one or more python scripts that are used to create the docs, and these are part of the testing system.

Two things they’ll have in common with the API docs:

  • they will have to be run in code from the folder where they are kept

  • they will output files that may/may not need to be copied to the correct docs location (some of them are set to write the files directly to where they are supposed to go), then committed.

The example and write-up sections are driven from a file (doc.py, often) that sits above the source files. That file’s main method will have a list of document files to build, and these are the files that make up the meat of the Python documentation. So, see the end of:

  • \3dec\blockpython\test\examples\doc.py

  • \flac3d\zonepython\test3d\examples\doc.py

  • \pfc\pfcpythonmodule\test3d\examples\doc.py

  • \common\python\test\examples\doc.py

Note

File locations for documentation are prone to alteration. The above are provided for reference but may have moved since this page was last updated.