Generating Documentation

besca's documentation

Besca's documentation is hosted using GitHub-pages. This means that all of the built HTML documentation is stored in a specific GitHub branch called gh-pages. The documentation is then accessible over the link https://bedapub.github.io/besca/besca.html. This ensures that it is easy to maintain an always up-to-date version of the documentation that is available online. Before you update the documentation for the first time you will have to perform some setup steps to initiate a new instance of the gh-pages branch. You will only have to perform this once for each local clone of the BESCA repository - after the initial setup any subsequent builds can easily be initiated by the steps described below. initially setting up gh-pages branch for storing documentation

1. In a bash terminal, navigate to the top folder of your local clone of the besca repository and move one directory further up
   cd ..

2. Create a new directory called 'besca-docs' in this location
   mkdir besca-docs

3. cd into this directory and initiate a new clone of the besca repository in a folder called 'html'
   git clone https://github.com/bedapub/besca.git html

4. move into this newly created directory called html and checkout the gh-pages branch
   git checkout gh-pages.

You should now have a current copy of the latest html build of besca's documentation. When you initiate a new build of the documentation in your local clone of the repository as described below the generated files will automatically be written to this newly initiated instance of the gh-pages branch. When you then commit and push these files to the central repository the central documentation will be updated.

generating up-to-date besca documentation

This process should be performed every time that something is merged into the master branch on GitHub to ensure that the documentation is always up-to-date. For this process to function you will need to setup a new instance of a gh-pages branch (see above) if you have not already done so.

1. Activate besca environment
   source activate besca

A minimum number of sphinx related packages are required. Please make sure to run :

conda install nbclean
conda install sphinx
conda install -c conda-forge sphinx-gallery
conda install -c conda-forge sphinx-automodapi
conda install -c conda-forge nbsphinx
conda install -c conda-forge sphinx_rtd_theme
conda install -c conda-forge pyyaml

if your enviromnent is incomplete for documentation generation

2. Build new html sphinx documentation Navigate to folder /besca/docs and run:
   make html

This will produce multiple warnings, which can normally be ignored (but it might be worth checking, especially if the next step doesn't work or something is missing in the resulting HTML).

3. Check that besca documentation has rendered as expected
4. Add new documentation to the gh-pages branch of GitHub. make buildandcommithtml

the commit and push will be initiated automatically to the correct location while performing a new html build, you will need to authenticate yourself with your GitHub account though.

5. Deactivate besca environment. source deactivate besca