Contributing to the InVEST User's Guide

The InVEST User's Guide is maintained in RST (reStructured Text) files that are rendered into the html pages seen here: http://releases.naturalcapitalproject.org/invest-userguide/latest/. This wiki explains the options for editing the User's Guide.

Both of these options require you to be logged into your github account. Option A requires that you are a member of the NatCap Github organization. If you are not a member but would still like to contribute changes, we welcome that. You must use Option B or C.

Option A: Directly edit rst files in this github repository

If the changes you wish to make are fairly small and quick (e.g. fixing a typo, adding/removing a few sentences), this is probably the best option. This is not a good option if the changes are substantial, will take time to complete, involve things like embedded content, or math equations.

1. Go to https://github.com/natcap/invest.users-guide/tree/master/source and click on the rst file you wish to edit.
2. Once you are on a page such as https://github.com/natcap/invest.users-guide/blob/master/source/delineateit.rst, click the pencil icon to edit the file.
3. At this point you see the raw rst file, and can make your edits. Use the "Preview Changes" tab to view your changes before saving them. Note that not all of the rst content can be previewed here. But it's useful for previewing text and headings. If you are changing more complicated content, you should probably use Option B or C.
4. If the changes look good, fill in the form at the bottom to "Commit Changes". If the changes were very minor, choose "commit directly to the master branch". If the changes are significant and you would like someone else to review them before they go live, choose "create a new branch and start a pull request" (although honestly you should probably be working with Option B in this case).
5. Any changes committed directly to the master branch will trigger an automated build of User's Guide. Once complete, the new version will be live at http://releases.naturalcapitalproject.org/invest-userguide/latest/. You may use the "Actions" tab at the top of this github page to view the status of the build.

Option B: Fork this repository and edit rst files on your forked github repository

If your edits are more substantial such that you might want more than one sitting to complete them, and/or want to save your progress incrementally along the way, then this is a good option.

1. Go to https://github.com/natcap/invest.users-guide and click the "Fork" button at the top-right. This will create a copy of the repository at github.com/"your username"/invest.users-guide.
2. Go to your fork of the User's Guide and edit rst files in the same manner described under Option A. Make as many incremental commits as you wish along the way in order to save the changes.
3. When all your changes are finished, find the "New Pull Request" button near the top of github.com/"your username"/invest.users-guide. "base repository" should be natcap/invest.users-guide and "head repository" should be `/invest.users-guide.
4. Write a note and click the green pull request button
5. Creating the pull request should trigger the User's Guide html to build (but it won't yet go live). You can find your pending Pull Request here https://github.com/natcap/invest.users-guide/pulls, select it, and then look at the "Actions". In the "Artifacts" section there should be a downloadable zip file. You may download it and view the html files to see exactly how your changes will look in the live version.
6. If after reviewing the html, you wish to make further edits, you may continue to do so on your fork. Any subsequent commits will automatically update the pending the pull request.
7. When it's ready, comment on the pull request that you have reviewed the HTML, and it looks good. Then a maintainer of the natcap/invest-users-guide repository will merge your pull request.

Option C: Clone this repository (or your own fork) and make changes locally

See this repository's readme file for notes on building the documentation locally, using sphinx and the Makefile, in order to review changes before pushing them back to github.

Extra: Guidance on reStructuredText syntax.

Here's a cheatsheet to help with commonly used formatting:

https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst

And here's an online tool for generating the rst for tables. It's even possible to import a CSV using this tool. Be sure to choose the reSturcturedText tab, there are ton of other formats available here.

https://truben.no/table/

Note that the User's Guide is built with Sphinx, and so there are a number of non-standard RST "directives" that are also present in the User's Guide but are not part of the official ReStructuredText language.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html