Contributing Documentation

Documentation for SELF includes API documentation generated by FORD as well as this documentation, which is published using mkdocs. We welcome contributions to help improve SELF's documentation from anyone. Simply make a fork of this repository, add or edit the documentation, and open a pull request. Now you might be asking yourself: "How do I edit documentation and preview my changes before opening a PR ?" This page should help you get started.

Updating FORD documentation

FORD API documentation is automatically generated by analyzing SELF source code. Additional documentation about the modules, classes, subroutines, and functions can be added through commentsthat are denoted with two exclamation points (!!) after the object you want to document. See the example below.

subroutine feed_pets(cats, dogs, food, angry)
    !! Feeds your cats and dogs, if enough food is available. If not enough
    !! food is available, some of your pets will get angry.

    ! Arguments
    integer, intent(in)  :: cats
        !! The number of cats to keep track of.
    integer, intent(in)  :: dogs
        !! The number of dogs to keep track of.
    real, intent(inout)  :: food
        !! The ammount of pet food (in kilograms) which you have on hand.
    integer, intent(out) :: angry
        !! The number of pets angry because they weren't fed.

    !...
    return
end subroutine feed_pets

To make changes to the FORD documentation, you will need the ford command line interface. You can easily install ford using pip

pip install --user ford

The SELF documentation has dependency graphs embedded by FORD, which requires graphviz. On Ubuntu and Debian OS, you can install graphviz with

sudo apt-get install graphviz

Once you've installed both ford and graphviz, you can re-generate the SELF API documentation by navigating to the root directory of the repository and running the following command :

ford self.md

This will update the docs/ford/ directory, which you can preview by opening docs/ford/index.html in your web brower.

See the FORD Documentation for more information on working with FORD.

Updating mkdocs documentation

The user and developer documentation, including this page you are currently reading, is developed using mkdocs. Before you start making changes, you will need to install the mkdocs command line interface in addition to a few add-ons that are necessary for previewing the documentation locally.

pip install user mkdocs mkdocs-material mkdocs-glightbox pymdown-extensions

Once installed, you can navigate to the root directory of this repository to start a local http server to view the pages.

mkdocs serve

To view the documentation, open 127.0.0.1:8000 or localhost:8000 in your web browser. From here, you can make edits to the documentation. As you save your changes, your preview will automatically update.

If you plan on adding new pages, you can add them under any of the appropriate subdirectories under docs/. If an appropriate subdirectory does not exist, make a new one to group your documents. To have your new pages appear in the navigation, you will also need to add it to the nav: block in mkdocs.yml