12. Updating the Python Doc Strings¶
We are still refining this procedure!
The Python doc strings for most functions in VisIt’s scripting interface are generated from the examples embedded in the
This allows us to have a single source for both our scripting interface sphinx docs and the doc strings embedded in VisIt’s compiled Python module.
functions_to_method_doc.py helper script generates
MethodDoc.C from the examples embedded in the rst source.
The Python doc strings for Attribute objects and Events are extracted from the scripting interface for use in the Python scripting sphinx docs.
sphinx_cli_extractor.py runs VisIt to generate
12.1. Steps to update the Python scripting manual¶
2to3 -p PY_RST_FUNCTIONS_TO_PYTHON.pyto check for Python syntax errors and Python 3 compatibly.
PY_RST_FUNCTIONS_TO_PYTHON.pyis just a temporary file to test steps 2 and 3 here. It could be named anything and is not part of the repository.
2to3will run to completion and issue a number of messages. A zero return code indicates all is well.
Build and run the VisIt scripting interface and assure yourself
help(<your-new-func-doc>)produces the desired output.
sphinx_cli_extractor.pytool producing new
events.rstfiles. To do so, you may need to use a combination of the
PYTHONPATHenvironment variables to tell the
sphinx_cli_extractor.pyscript where to find the VisIt module,
site-packagesand where to find the Python installation that that module is expecting to run with. In addition, you may need to use the
PYTHONHOMEenvironment variable to tell VisIt’s
visitmodule where to find standard Python libraries. For example, to use an installed version of VisIt on my macOS machine, the command would look like…
env PATH=/Applications/VisIt.app/Contents/Resources/2.13.3/darwin-x86_64/bin:/Applications/VisIt.app/Contents/Resources/bin:$PATH \ PYTHONHOME=/Applications/VisIt.app//Contents/Resources/2.13.3/darwin-x86_64/lib/python \ PYTHONPATH=/Applications/VisIt.app/Contents/Resources/2.13.3/darwin-x86_64/lib/site-packages \ ./sphinx_cli_extractor.py
Note that the above command would produce CLI documentation for version 2.13.3 of VisIt. Or, to use a current build of VisIt on which you are working on documentation related to changes you have made to VisIt, the command would look something like…
env PATH=/Users/miller86/visit/third_party/3.2.0/python/3.7.7/i386-apple-darwin18_clang/bin:/Users/miller86/visit/visit/build/bin:$PATH \ PYTHONPATH=../../build/lib/site-packages python3 ./sphinx_cli_extractor.py
The whole process only takes a few seconds.
Assuming you successfully ran the above command, producing new
events.rstfiles, then do a local build of the documentation here and confirm there are no errors in the build.
sphinx-build -b html . _build -a
Then open the file,
_build/index.html, in your favorite browser to view.
Add all the changed files to a commit and push to GitHub.
The GitHub integration with ReadTheDocs should result in your documentation updates going live a short while (<15 mins) after it has been merged to develop.