Working on project docs

The documentation for this project (this documentation, that you are reading right now, on the interweb) is part of the project repository. The HTML files that your web browser is currently rendering for you so that you can read these words are located in the docs directory of the project. We told GitHub to find the HTML documentation in this directory, and to serve it on the web.

The HTML files in docs were automatically generated by Sphinx from the source files in the docs-source files. The source files in docs-source are in reStructuredText format. You can find a nice introduction to reStructuredText on this page of the Sphinx documentation It’s a format that is easy to read and write for humans, but still structured enough for software like Sphinx to parse and convert it into other formats like HTML, PDF, etc.

If you notice any errors in the documentation, or would like to improve or add to it in any way, please feel free to do so by editing the contents of the docs-source directory. If you do so, you will probably want to clone a copy of the repository to your computer, so that you can easily compile and look at the HTML files to see how your changes look. I say this, because members of the Phyletica Lab are working on the analyses for this project on a cluster. Working the docs will be easier on your own computer.

To clone a copy to your computer, navigate to where you want to have the project and enter:

git clone git@github.com:phyletica/ecoevolity-model-prior.git

When you want to work on the documentation, just cd to the docs-source directory:

cd ecoevolity-model-prior/docs-source

From there, all of the reStructuredText files are in the source directory. If you compare the contents of these files to the HTML documentation online, you should start to be able to find your way around the content (though reStructuredText format might take a little getting used to).

Inside the docs-source directory is a file called docs-conda-environment.yml. This file tells conda how to create a Python environment with all the packages needed to use Sphinx to build the HTML documentation files from the reStructuredText files in docs-source/source. Go ahead and run these to commands to create and activate this environment:

conda env create -f docs-conda-environment.yml
conda activate ecoevolity-model-prior-docs

Now, you should be able to use Sphinx to build the HTML documentation. Just cd into the docs-source directory of this project and run:

make html

This will create all the HTML files and put them in the docs-source/build directory. If you open the docs-source/build/index.html file with your web browser, you should be able to view the documentation as it would appear on the web.

Now, you can edit the files in docs-source/source all you want, and then run make html from inside the docs-source whenever you want to preview what the documentation website will look like with your changes.

As you work on the files in docs-source/source, I encourage you to use git add, git commit, and git push often to keep track of your work. Also, remember to use git pull often to make sure your copy of the project repository is up to date as you work. A lot of version-control misery can be avoided by committing/pushing and pulling often!

Once you are happy with your changes and want them to appear on the project site, you can enter the following command form within the docs-source directory:

make publish

This will use Sphinx to create all the HTML files in the docs-source/build, copy them all to the docs directory of the project, and then use git to add, commit, and push all changes to docs and docs-source/source. Within a few minutes (usually), the project site should be updated.