Contributing To VisIt CLI Documentation¶
Note: This procedure is planned for change in the future.
At present, all VisIt Python CLI documentation is actually composed directly
as Python strings in the source C++ file in ../../visitpy/common/MethodDoc.C
.
We recognize this isn’t the most convenient way to write documentation and are
planning on changing it in the future. However, it does permit us to have a
single source file for documentation which is then used to provide help(func)
at the Python prompt as well as generate the restructured text used here.
In the future, we will swap this arrangement and write documentation in
restructured text and then generate the contents of ../../visitpy/common/MethodDoc.C
from the restructured text.
The documentation here is then generated from the MethodDoc.C
file using the script
../sphinx_cli_extractor.py
. That script produces attributes.rst
, events.rst
and functions.rst
files. The other .rst
files here are manually managed and can
be modified normally as needed.
Steps to update the CLI Manual¶
Modify
../../visitpy/common/MethodDoc.C
as neededBuild and run the VisIt cli and assure yourself
help(<your-new-func-doc>)
produces the desired outputRun the
sphinx_cli_extractor.py
tool producing newattributes.rst
,events.rst
andfunctions.rst
files. To do so, you may need to use a combination of thePATH
andPYTHONPATH
environment variables to tell thesphinx_cli_extractor.py
script where to find the VisIt module,visit
in VisIt’ssite-packages
and where to find the Python installation that that module is expecting to run with. In addition, you may need to use thePTHONHOME
environment variable to tell VisIt’svisit
module where to find standard Python libraries. For example, to use an installed version of VisIt on my OSX 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=../../build/third_party/python/2.7.14/i386-apple-darwin17_clang/bin:../../build/visit/build/bin:$PATH \ PYTHONPATH=../../build/visit/build/lib/site-packages/ \ ./sphinx_cli_extractor.py
The whole process only takes a few seconds.
Assuming you succesfully run the above command, producing new
attributes.rts
,events.rst
andfunctions.rst
files, then do a local build of the documentation here and confirm there are no errors in the buildsphinx-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.