📃 Writing Documentation

If you’re contributing a new feature to exoatlas, please consider also contributing some documentation to explain how your feature works. Here’s the very short version of how to add to the documentation:

1. Install in development mode (see Installation), so you have access to mkdocs and the various extensions needed to render the documentation.

2. Decide whether your explanation would fit well within an existing page or whether you need a new one. In the docs/ directory, find the appropriate .ipynb notebook file or create a new one. If you create a new one, add it to the nav: section of the mkdocs.yml file in the main repository directory so that mkdocs will know to include it.

3. Write your example and explanation in a .ipynb file. Your audience should be smart people who want to use the code but don’t have much experience with it yet. Be friendly and encouraging!

4. From the Terminal, run mkdocs serve. This will convert all of the source notebooks into a live website, and give you a little address that you can copy and paste into a browser window. While that mkdocs serve command is still running, small changes you make to existing .ipynb source files will appear (sometimes after a few minutes) on the live locally-hosted webserver.

5. Once you’re happy with your new documentation, before committing it to the repository, please run “Kernal > Restart & Clear Output” or something similar to remove all outputs from the source notebook file. The exoatlas repository will hang onto all changes that you commit to it, so it would very quickly get annoyingly large unless we leave the outputs out of committed notebook files. Double check the outputs are all gone, save your notebook, and then commit it to the git repository (see Contributing Code with GitHub).

Periodically, after reviewing and copy-editing the documentation, we’ll deploy the newest version up to the web at zkbt.github.io/exoatlas/ for all to enjoy.