README.rst

Documentation

This subdirectory contains the reStructuredText documentation that can be built with sphinx.

Build the documentation

To build the documentation, you need ensure that you have installed the packages in doc_requirements.txt. If these packages are not installed, you can install them with:

pip -r doc_requirements.txt

Then simply type:

make html

and the HTML documentation will be built in _build/html/. You can open the HTML files in that directory to see how the docs look.

Jupyter notebooks as examples

The documentation is set up to include Jupyter notebooks via nbsphinx. Assuming you have them in the ../notebooks/ subdirectory, you need to use nbsphinx-link to include them. For instance, if you have a notebook at the path ../notebooks/example_notebook.ipynb, then you would first create a file in this docs directory called example_notebook.nblink with the following contents:

{
    "path": "../notebooks/example_notebook.ipynb"
}

You would then simply include the notebook by adding example_notebook to one of your *.rst files (e.g., examples.rst) the same way that you would link to another *.rst file.

Pushing docs to GitHub pages

The docs are hosted on GitHub pages at https://jbloomlab.github.io/alignparse

After you have built the documentation as described above, here is how you push it to GitHub pages:

Building the documentation for the first time

If you are building the docs for the very first time, then there will not be any branch called gh-pages on the project's GitHub repo. In that case, you need to create that branch in the _build/html/ subdirectory.

First, clone the repo into _build/html/:

mkdir _build
git clone https://github.com/jbloomlab/alignparse _build/html

Then create a new branch called gh-pages in this subdirectory:

cd _build/html
git checkout -b gh-pages

Now go back to the top directory of the docs, remove all the existing files in _build/html, and build the sphinx docs into this directory:

cd ../../
make html

Now got into _build/html and commit this initial version of your docs:

cd _build/html
git add .
git commit -m 'initial build of `gh-pages` docs'

Finally, push the gh-pages branch to GitHub:

git push -u origin gh-pages

After a few minutes, your docs should now show up at https://jbloomlab.github.io/alignparse

Building a new version of the docs

If you have already built and earlier version of the docs that gh-pages already exists, then you simply need to commit a new version.

First, remove any existing docs:

make clean

Now clone the existing gh-pages branch in _build/html:

git clone -b gh-pages https://github.com/jbloomlab/alignparse _build/html

Next, build the docs:

make html

Finally, commit and push this new version of the docs:

cd _build/html
git add --all
git commit -m 'new version of docs'
git push