search

hubverse-org / hubDocs

https://hubverse.io
5 stars 6 forks source link

readme

Documentation for Infectious Disease Modeling Hubs

This GitHub repository includes the content needed to generate the static site that contains the documentation about how to build, manage and maintain collaborative modeling hubs.

Sections

  1. How the site works
  2. Installation and building
  3. View local site
  4. Documentation versioning
  5. Contribution guidelines
  6. Style notes

How the site works

This site uses ReadTheDocs and Sphinx for building and maintaining the content. The live version of the documentation can be found in this page.

The main content of the site lives in docs/source. That is where you will add/edit Markdown files to populate the content of the site.

This page provides useful documentation on how to use the Jupyter Book theme, which is the theme currently used by our documentation site.

Installation and building

To build and preview the site locally, the following steps (assuming you already have python installed) are adapted from the ReadTheDocs site:

  1. Install sphinx: pip install sphinx.
  2. We are using MyST to enable Markdown, so you need to install myst-parser: pip install myst-parser.
  3. Install the theme we are using: pip install sphinx-book-theme. Documentation on theme-specific elements can be found here.
  4. In the docs folder, run make html to build the site locally to inspect changes.

Using a conda environment for local development

It is preferable to work with the project in a project specific conda environment. For this you will need Anaconda or Miniconda installed.

You can check whether conda is installed by running conda list. If conda is installed and working, this will display a list of installed packages and their versions.

Create environment and install dependencies

You first need to create a python 3.9 hubdocs environment and install all additonal python dependencies within it.

# Create hubdocs environment containing python 3.9
conda create -n hubdocs python=3.9

# Activate hubdocs environment
conda activate hubdocs

# Install python dependencies
pip install -r docs/requirements.txt

Activate environment

Any time you return to the project, you will need to activate the hubdocs environment.

# Activate hubdocs environment
conda activate hubdocs

Deactivate environment

When finished, you can deactivate the conda environment with:

conda deactivate

Build site

To build html pages from source, navigate to the docs/ directory and run make html. The resulting HTML pages can be found in the docs/build/ directory.

cd docs
make html

View local site

To view the site locally, open any of the html files the docs/build/ directory in a browser (by right clicking and selecting the application to open the file with.)

Using Live Server in VSCode

If you are using VSCode, you can use the Live Server extension to run a live version of the site which will update in real time as you make changes.

To use Live Server:

  1. Make sure the extension is installed on your system. Install it from VSCode Marketplace
  2. Once installed, a Go Live button will appear at the bottom of left of the VSCode toolbar when viewing any html file. Clicking on it launches a live server on the open html file page.
  3. When the Live Server is running, you will see the port it it is being served on at the bottom of left of the VSCode toolbar.
  4. To disconnect the server, click on :no_entry_sign:.

Documentation versioning

Documentation is versioned by using releases. Releases should track releases of Hub schema versions in schemas repository. While changes to documentation text can be commited without creating a new release and will appear in the latest version of the documentation, changes to documentation related to a new schema release must be accompanied by a new release in this repository. New releases on hubDocs should use the same version number as the schemas release but without the v (e.g. a v0.0.1 schemas version number would be released as 0.0.1 on hubDocs).

When creating a new release version:

  1. Checkout the main branch and ensure you pull all changes from the remote repository.
  2. Create a new branch of the main branch and name it using the convention br-<version-number>
  3. Open docs/source/conf.py file and update the value of the schema_version variable with the version of the schema in the schemas repository you want the release to accompany (e.g. v0.0.1). This propagates the appropriate version to various substitution text elements within the docs, including the URLs pointing docson widgets to raw config schema files.
  4. If the version of the schema you are preparing the release for has not been released to main branch in the schemas repository, you can set the value of the schema_branch variable to the name of the branch in the schemas repository in which the version is being prepared (e.g. br-v1.0.0). This allows you to see what development versions of the schema will look like in the docson widgets while developing locally and in a pull request. If the schema has been released to main in the schemas repo, set schema_branch to "main". The value of this variable is overriden automatically when READTHEDOCS builds the documentation on the main branch (or any other branch for that matter, in contrast to a pull request build) after a merge or a new release.
  5. Any any changes to the documentation needed.
  6. Commit and push changes (including changes to conf.py)
  7. Create pull request and merge after review.
  8. Create a release on GitHub labelling it with the same version number as the schemas release this release is associated with but without the v (e.g. a v0.0.1 schemas version number would be released as 0.0.1 on hubDocs).

Contribution guidelines

In general, contributions should be made via pull requests to the main branch. Note that PRs should trigger preview builds of the site, so you should be able to double-check that your changes look as expected.

Style notes