Documentation about the documentation

These docs are built using Sphinx and served on github. They use the actual input and output used for the example pipeline run, so generation of the docs requires successfully running the example pipeline.

Here’s how to rebuild and upload the docs.

Note

All paths below are relative to the top-level dir of the repo

Run the pipeline on example data

The documentation includes customized DAGs of the workflows. To generate these, first the example pipeline must have been successfully run. Here’s how to do that on the biowulf cluster:

./clean-example-data.sh
module load bedtools R  # on biowulf
snakemake -npr -s Snakefile  # dry run
snakemake -pr -s Snakefile  # run everything

If you have made any changes to the documentation, make sure you commit them now:

git status

Note

The following commands assume your latest work was on the master branch. This is generally a good assumption because it means that the docs match the code in master. But merging from another branch might be useful if you’re playing around with changes to the docs themselves.

Run build-docs.sh

Run:

./build-docs.sh

This will build and upload docs to the currently-configured origin. If this is run on your fork of the P3 code, it will upload the docs to your fork, such that you can view it at:

<username>.github.io/Pharmacogenomics_Prediction_Pipeline_P3

If you would like to build and upload for another repo that you have write access to – say, to update the docs in the main repo – then pass that repo as the first argument to build-docs.sh. E.g.,:

./build-docs.sh git@github.com:NCBI-Hackathons/Pharmacogenomics_Prediction_Pipeline_P3.git

Merge master with gh-pages branch

Relative to the top-level dir of the repo:

git checkout gh-pages
git merge master

Make the docs while in the gh-pages branch

cd doc
make dags
make clean html

Check output and push to github

In a browser, check the built docs at doc/build/html/index.html. If everything looks OK, you’re ready to push to github:

git status
git commit -a -m 'rebuild docs'
git push origin gh-pages

Switch back to master branch

And finally, get back to the master branch:

git checkout master
<username>.github.io/

View docs on web

Now check the new docs (might need to force refresh) at http://ncbi-hackathons.github.io/Pharmacogenomics_Prediction_Pipeline_P3/doc/build/html.