Documentation and Development

Building the Docs

The recommended way to build the docs is through a docker image, which is managed with docker-compose:

# optional, if you built previously:
docker-compose rm -f
# Create and run the documentation service:
docker-compose -f docker-compose.yml up --build documentation
# build the documentation service
docker-compose -f docker-compose.yml build documentation
# Create the documentation.
docker-compose run --rm documentation

This runs the CMD of the systemsgenetics/gsforge_documentation Docker file which:

  1. Builds the API with sphinx-apidoc.

  2. Builds the website and run the notebooks with sphinx.

Most reference examples are executed during the travis continuous integration build process, while the walkthroughs and some of the notebooks take too long to run, and must be executed locally. This is enforced by saving files that should be run every time as markdown files .md to be processed as notebooks automatically by MyST. All jupyter notebooks should be run prior to updating the main branch.

Notebooks can be executed from the command line via:

# Execute a single notebook.
jupyter nbconvert --to notebook --execute --inplace docs/source/user_guide/tour.ipynb
# Execute multiple notebooks.
jupyter nbconvert --to notebook --execute --inplace docs/source/walkthroughs/oryza_sativa/*.ipynb

Resources

A number of tools are required to build the package components and documentation:

  • sphinx <https://domain.invalid/>

  • jupyter <https://domain.invalid/>

  • nbconvert <https://domain.invalid/>

  • paramdoc <https://domain.invalid/>

  • MyST <https://domain.invalid/>

  • Github pages <https://domain.invalid/>

  • Docker <https://domain.invalid/>

  • DockerHub <https://domain.invalid/>

  • Travis Continuous Integration <https://domain.invalid/>

Most of these components are managed using travis continuous integration. The exception being those demonstrations of tools external to GSForge, such as the tour notebook, workflow executions, and the walkthroughs, which must have their results committed to the git repository.

Travis CI Integration

GSForge is maintained via travis ci integration. A build will initialize upon: travis will build and update the documents, then update the pip, docker and conda repositories.

  • Upon pushing a tagged commit (that matches the regex string in travis.yml file) to the master branch

  • a commit tag that matches the development regex, or when travis_dev is in a commit message.

This development run deploys documentation to https://systemsgenetics.github.io/GSForgeDev/index.html.

OSF Data Repository