Development¶

Overview¶

Maintaining GSForge involves:

• PyPi package index.
• Documentation website
  • hosted by github pages
  • Built with nbsite, a version of sphinx which is used by Readthedocs.
• Docker images
  • Interactive image, this is likely to be the source for a future 'SciAPP' as well.
  • Workflow images.

The above repositories and websites are all kept up-to-date using travis ci.

Travis CI¶

Travis integration is setup through the .travis.yml file.

Generating the Documentation¶

Prerequisites:

• nbsite This is a requirement for the classes defined based upon param.Parameterized to render nicely. nbsite is essentially a wrapper for a call to sphinx-build, with some additional tools to handle jupyter notebooks. This means that sphinx can be used as normal, including being configured via doc/conf.py.
• nbsmoke For basic notebook checks.

Initial setup notes:

The documentation is generated per the usage docs of nbsite. See the .travis.yml file to see how nbsite is called to build the docs.

Maintaining the Docs¶

1. Ensure that all .rst files have their table of contents (toc) updated.
2. Notebooks
   • If a notebook is removed, ensure the corresponding .rst file is no longer in the repository.
   • Notebooks are evaluated upon each update to the documentation, unless the evaluated notebook is found locally, or an .rst directive declares :skip_execute: True. Therefor .rst files that must have non-default directives must be added to the repository.
3. API
   • The docstrings within GSForge are written with RestructuredText.
   • The core classes are built upon param.Parameterized, ensure parameters are documented.

More on Notebooks¶

Normally notebooks are viewed by an restructured text directive. These container files are constructed automatically during the travis build via:

nbsite generate-rst --org SystemsGenetics --project-name GSForge

If a notebook should not be run by travis for whatever reason, the containing .rst file should be generated using the above command. Then the directive can be modified by setting the skip_execute option to True.

.. notebook:: GSForge ../relative/path/to/notebook.ipynb
    :offset: 0
    :skip_execute: True

The offset option controls how many cells are to be skipped. This is there since the default uses the notebook name as the displayed title.

Testing Notebooks (optional)

You can test if all of the example notebooks run with nbsmoke (this is what the travis ci will do) to check if they all run.

pytest --nbsmoke-run examples/**/*.ipynb

Maintaining Docker Images¶

The docker images used by GSForge are based on the Jupyter Docker Stacks.