These source files, in restructured text format, are designed to be compiled into stand-alone HTML documents (and sometimes PDF) using the Sphinx documentation generator (http://sphinx.pocoo.org/).
See requirements.txt for the python dependencies required to build the documentation.
Some source files reference tables from the invest-sample-data repo.
A clone of invest-sample-data must exist in the top level of this repo before you build the documentation.
Execute the following command to clone invest-sample-data and check out the correct revision:
make get_sampledata
Execute the following command to build HTML documentation from the reStructuredText source:
make html
Then find the html documents in build/html and view them in a web browser to evaulate for correctness.
Edits to the User Guide that pertain to the currently released version of InVEST can be made directly on this repo's main branch.
Edits that pertain to a yet-to-be-released feature of InVEST should be made on the corresponding release/X.X branch in this repo. That branch should be merged into main at the same time as the corresponding invest release.
Our style guide google doc is actively being developed. For anything not listed in our style guide, follow the Google developer documentation style guidelines.
requirements.txt is the complete list of requirements needed to build the user's guide.
However, pip install -r requirements.txt will fail in a fresh environment because natcap.invest depends on gdal, which cannot be pip installed unless the GDAL library and headers already exist on the system.
Since the GDAL library and headers can be installed with conda, an environment.yml is included that will install GDAL with conda, and then the rest of the requirements with pip.
Nothing special needs to be done when routinely editing the source RST files. See the InVEST internationalization README for more background.
There are three components of the user's guide that have separate mechanisms of translation: text in the source RST files; text provided by Sphinx such as "Note" or "Warning"; and text that's imported from natcap.invest by the custom :investspec: role.
All commands below should be run from the project root directory, and <LANG> should be replaced with the appropriate ISO 639-1 language code.
Run make gettext to extract the messages and create new POT files. This uses the Sphinx gettext builder to extract a message from each document node. This is nice because it works without having to modify the source RST in any way. There will be one POT file for each source RST file and they will be created in build/gettext.
Update the PO files for the language from the new POT files:
$ sphinx-intl update --locale-dir source/locales --pot-dir build/gettext --language <LANG>
Or to update PO files for all languages:
$ sphinx-intl update --locale-dir source/locales --pot-dir build/gettext
Send the PO files in source/locales/<LANG>/LC_MESSAGES to the translator for the language. The translator will fill in the translations and send them back.
Replace the PO files in source/locales/<LANG>/LC_MESSAGES with the updated ones from the translator.
Update the relevant translations in natcap.invest (see the InVEST internationalization README).
Follow the same directions above to update translations. The sphinx-intl update command will create new PO files for a language if it doesn't already exist.
The language will most likely be on the list of languages supported by Sphinx, and so nothing needs to be done. But if not, we'll need to figure out how to provide our own message catalog for Sphinx-generated messages.
Make sure that natcap.invest supports the new language as well (see the InVEST internationalization README).
make SPHINXOPTS="-D language=<LANG>" html