This documentation is build with Sphinx. To build locally, you will need to install Python 3.
It is recommended that you use a virtual environment for repeatability purposes. First, create a virtual environment
(called env by default, but can be named other things):
python -m venv env
Activate the virtual environment on Linux/MacOS/any POSIX system:
. env/bin/activate
if using bash or zsh or other modern shells, you can use the source alias for .:
source env/bin/activate
or with Powershell on Windows:
env\Scripts\activate
From here, you can install the frozen package versions inside the virtual enviroment:
pip install -r requirements.txt
You're ready to go!
If you are interested, the packages for manual installation are:
pip install -U sphinx sphinx-rtd-theme sphinx-last-updated-by-git
The HTML and PDF documentation can be build with:
python build.py --latex
To skip PDF building (for example, if you don't have a local LaTeX install), run:
python build.py
Build output is in the folder output. The HTML version can be loaded by clicking on output\html\index.html.
If you run into strange Sphinx errors upon building, the output directory may have been corrupted. In this case, close any programs (e.g. Windows Explorer, Adobe Acrobat) accessing the built documentation and run:
python build.py --force-rebuild
This command will first remove the output directory before continuing.
This documentation is also automatically build and published to https://gallowaylabmit.github.io/protocols on every push.
Protocol files are written in the reStructuredText format, a relatively lightweight markup language. See the linked primer for details on how to make tables, link images, or link to other protocols. All protocols are located in the docs folder.
This project has one custom directive: an estimated time directive. To use it, simply write:
.. time:: 35 billion years
The empty line after the directive is important! Remember that reStructuredText directives need that empty line to distinguish them from other text.
When adding a new protocol, ensure that it has a title so it shows up properly in the table of contents! The title is the first piece of text surrounded by equal signs. An example protocol:
=================
The best protocol
=================
.. time:: 3 hours
Protocol
========
1. Prep the cool science.
2. Do the cool science.
3. Clean up the cool science.
.. note::
1. Make sure to read this before starting!
If you want to add additional structure to the protocols, the easiest way to do it is to add a new subfolder. Inside that folder, add a file index.rst with the following:
=================
Subsection name
=================
.. toctree::
:maxdepth: 2
:glob:
*
This will auto-include all other *.rst files present in the same directory. If you are doing further nesting, you may want to include the glob */index to include all subdirectories as well. An example of this is in docs/protocols/index.rst.
These protocols are available under the Creative Commons 4.0 Attribution International license. Use, share, and modify freely, with attribution!