ReadtheDocs Guide¶
Documentation for our generic modules should be written in **Restructured Text**, compiled with Sphinx, and built/hosted with ReadTheDocs. This directory, when compiled, is hosted at https://[yourmodule].readthedocs.io/en/latest/
For minor changes, you can simply Edit the file using the Github editor, which will allow you to make a Pull Request. Once approved, your changes will be reflected in the documentation automatically!
Install Sphinx¶
For minor changes, you don’t need to build the documentation! If you want to see how your changes will look on the built site, however, you will need Sphinx installed.Sphinx packages are published on the Python Package Index. The preferred tool for installing packages from PyPI is pip. This tool is provided with all modern versions of Python.
On Linux or MacOS, you should open your terminal and run the following command.
$ pip install -U sphinx
After installation, type sphinx-build --version
on the command prompt. If everything worked fine, you will see the version number for the Sphinx package you just installed.
For more information, please see the Sphinx setup guide: http://www.sphinx-doc.org/en/master/usage/quickstart.html
Building your changes¶
For more extensive edits, or when contributing new guides, you should build the documentation locally. From the docs
root (e.g. [your module]/docs/
, execute make html
. The built site will be in docs/_build/html/index.html
.
Guidelines¶
Please follow these guidelines when updating our docs. Let us know if you have any questions or something isn’t clear.
Please place images in the same folder as the guide text file, following the convention [file_name].[n].[optional description].[extension]
. For example, configuring_page_display.3.rearrange.png
or configuring_page_display.1.png
are both located in docs/user_guide/
and are part of the configuring_page_display.rst
guide.
We currently use the following syntax:
Title of File (using title case)
=================================
Introduction text.
.. note::
This would show up as a boxed note to the reader. It's good for ensuring important points/hints are seen but should be used sparingly. It's also a good way to note that "This guide is under developement."
Section Title
-------------
We use double backticks to indicate ``inline-code`` including file names, function and method names, paths, etc.
Longer code-blocks should begin with the ``.. code-block:: [type]`` directive and should be indented at least one
level. There should also be a blank line before and after it as shown below.
.. code-block:: bash
if ($needs_documentation) {
use $these_guidelines;
$contribute_docs = $appreciated;
}
Section 1.1 Title
^^^^^^^^^^^^^^^^^
The use of appropriate sections makes reading documentation and later specific details easier. Sub sections such
as this one will be hidden unless the main section is already selected.
The following toctree specifies that there are 3 files with additional content for the current page.
The order is as it will appear in the sidebar and the link titles will be the "Title of File" for each file.
.. toctree::
:maxdepth: 2
:caption: Contents:
dir/file1
dir/file2
dir/file3
For more information on syntax, see this RestructuredText Primer.
Starting Docs for a new Module¶
- Install sphinx using pip and navigate yourself into git directory.
- Create a
docs
folder there and go inside. Runsphinx-quickstart
and set to your needs. Simply accept the defaults except for:
The project name will occur in several places in the built documentation.
> Project name: Genotypes Loader
> Author name(s): Carolyn T Caron et al., University of Saskatchewan, Pulse Bioinformatics
> Project release []:
- Create one .rst document per planned section and populate it accoding to the guidelines above. If a given section is long enough to be broken up into sub-sections then create a folder with the same name as [your section].rst and place all .rst files for that section within it.
- For each .rst file, ensure it is added to the
toctree
for that section. The base sections should be added to the index.rst - Edit the
index.rst
: change the title to[My Module]: Available Documentation
and remove theIndices and Tables
section. - Ensure your conf.py matches the one provided here. by comparing each section. Do not change your
project information
and pay special attention toPHP Highlighting
andOptions for HTML output
. - Copy
_static
from this repo to yourdocs
folder. This contains the UofS-Pulse-Binfo theme alterations. - Build your documentation using
make html
and check_build/html/index.html
to ensure your documentation looks as it should. - Add
_build/
to your.gitignore
file and commit your changes pushing them out to github. - Go to
https://readthedocs.org/dashboard/
and add this module as a project.
Note
If Theme error: no theme named 'sphinx_rtd_theme' found (missing theme.conf?)
is encountered in step 8. This error indicates sphinx theme package sphinx-rtd-theme is not available in your system and it can be installed by executing following command on Linux or MacOS.
sudo pip install sphinx-rtd-theme