Updating the Documentation
The documentation for PHENIO is managed in two places (relative to the repository root):
- The
docs
directory contains all the files that pertain to the content of the documentation (more below) - the
mkdocs.yaml
file contains the documentation config, in particular its navigation bar and theme.
The documentation is hosted using GitHub pages, on a special branch of the repository (called gh-pages
). It is important that this branch is never deleted - it contains all the files GitHub pages needs to render and deploy the site. It is also important to note that the gh-pages branch should never be edited manually. All changes to the docs happen inside the docs
directory on the main
branch.
Editing the docs
Changing content
All the documentation is contained in the docs
directory, and is managed in Markdown. Markdown is a very simple and convenient way to produce text documents with formatting instructions, and is very easy to learn - it is also used, for example, in GitHub issues. This is a normal editing workflow:
- Open the
.md
file you want to change in an editor of choice (a simple text editor is often best). IMPORTANT: Do not edit any files in thedocs/odk-workflows/
directory. These files are managed by the ODK system and will be overwritten when the repository is upgraded! If you wish to change these files, make an issue on the ODK issue tracker. - Perform the edit and save the file
- Commit the file to a branch, and create a pull request as usual.
- If your development team likes your changes, merge the docs into main branch.
- Deploy the documentation (see below)
Deploy the documentation
The documentation is not automatically updated from the Markdown, and needs to be deployed deliberately. To do this, perform the following steps:
- In your terminal, navigate to the edit directory of your ontology, e.g.:
cd phenio/src/ontology
- Now you are ready to build the docs as follows:
Mkdocs now sets off to build the site from the markdown pages. You will be asked to
sh run.sh make update_docs
- Enter your username
- Enter your password (see here for using GitHub access tokens instead) IMPORTANT: Using password based authentication will be deprecated this year (2021). Make sure you read up on personal access tokens if that happens!
If everything was successful, you will see a message similar to this one:
INFO - Your documentation should shortly be available at: https://monarch-initiative.github.io/phenio/