chaosphere2112
commented
7 years ago - Building Documentation:
- The immediate process is pretty easy (important: you must have VCS and sphinx installed in your current conda environment. Sphinx is a part of the base conda env, but it has to import vcs, so you need it installed in the same environment in order to run)
cd vcs/docs make html make pdfThese will output to
vcs/docs/_build/htmlandvcs/docs/_build/latexrespectively. - Eventually should work on getting this done as part of the tagging process (and possibly maintaining a nightly version of the docs to go with the builds pushed to the nightly label)
- The immediate process is pretty easy (important: you must have VCS and sphinx installed in your current conda environment. Sphinx is a part of the base conda env, but it has to import vcs, so you need it installed in the same environment in order to run)
- Doc Strings:
- These are automatically imported by the documentation. They're formatted using Restructured Text, not markdown (though they look very similar) and include commands for Sphinx, the documentation engine that we're using.
- Doc Tests:
- @doutriaux1 is working on integrating these with the test suite, so they should be automatically run and basically not your problem. The VCS developers should be adding them as they add new functionality, in theory, and at a minimum will be keeping them up to date so the build doesn't break. Guides to doctests: https://docs.python.org/2.7/library/doctest.html
- Brain dump:
- I don't actually have a lot to dump for this project; it's been pretty stable. We need to look into getting the jupyter notebook stuff handled automatically as part of the build process (I'd recommend basically just having a daily cron that pulls down a separate repo, builds the html, and dumps it into the _site directory to be served).
mattben
Wrong repo….
https://uvcdat.llnl.gov/docs/index.html