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. While you certainly can work on the source files for the documentation on the cluster, it will probably be more “comfortable” for you to do so on your own computer.

To clone a copy to your computer, navigate to the directory where you want to keep 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 are files called setup_docs_env.sh and docs-python-requirements.txt. The former is a shell script that uses the latter to create a Python virtual environment that has all the necessary packages necessary 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:

bash setup_docs_env.sh
source pyenv-docs/bin/activate

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.

Note

You should only edit the source files in docs-source/source, and NOT the files in docs-source/build or docs. This is because the files in docs-soure/build and docs are automatically generated by Sphinx, so changes to those files will get overwritten the next time Sphinx is used to generate the documentation website.

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.