Updating the Documentation
The documentation for UPHENO is managed in two places (relative to the repository root):
docsdirectory contains all the files that pertain to the content of the documentation (more below)
mkdocs.yamlfile cotains 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
Editing the docs
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
.mdfile you want to change in an editor of choice (a simple text editor is often best). IMPORTANT: Do not edit any files in the
docs/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 master 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.:
- Now you are ready to build the docs as follows:
sh run.sh make update_docsMkdocs now sets off to build the site from the markdown pages. You will be asked to
If everything was successful, you will see a message similar to this one:
INFO - Your documentation should shortly be available at: https://obophenotype.github.io/upheno/
3. Just to double check, you can now navigate to your documentation pages (usually https://obophenotype.github.io/upheno/).
Just make sure you give GitHub 2-5 minutes to build the pages!