==========================
Updating the Documentation
==========================

The documentation for NMDO is managed in two places (relative to the repository root):

1. The ``docs`` directory contains all the files that pertain to the content of the documentation (more below)
2. 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:

1. 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 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 <https://github.com/INCATools/ontology-development-kit/issues>`_.
2. Perform the edit and save the file
3. Commit the file to a branch, and create a pull request as usual.
4. If your development team likes your changes, merge the docs into main branch.
5. 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:

1. In your terminal, navigate to the edit directory of your ontology, e.g.:

   .. code-block:: shell

       cd nmdo/src/ontology

2. Now you are ready to build the docs as follows:

   .. code-block:: shell

       sh run.sh make update_docs

   `Mkdocs <https://www.mkdocs.org/>`_ now sets off to build the site from the markdown pages. You will be asked to:

   - Enter your username
   - Enter your password (see `here <https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token>`_ 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 <https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token>`_ if that happens!

   If everything was successful, you will see a message similar to this one:

   .. code-block:: text

       INFO    -  Your documentation should shortly be available at: https://NeuromuscularDisease.github.io/neuromuscular-disease-ontology/

3. Just to double check, you can now navigate to your documentation pages (usually https://NeuromuscularDisease.github.io/neuromuscular-disease-ontology/). Just make sure you give GitHub 2-5 minutes to build the pages!