Writing Documentation

FORD usage is based on projects. A project is just whatever piece of software you want to document. Normally it would either be a program or a library. Each project will have its own Markdown file which contains a description of the project. For details on some of the non-Markdown syntax which can be used with FORD, see below. Various options can be specified in this file, such as where to look for your projects source files, where to output the documentation, and information about the author. See ./example-project-file.md for a sample project file.

Other documentation is placed within the code. This is described in more detail below.

Indicating Documentation

In modern (post 1990) Fortran, comments are indicated by an exclamation mark (!). FORD will ignore a normal comment like this. However, comments with two exclamation marks (!!) are interpreted as documentation and will be captured for inclusion in the output. If desired, the character(s) designating documentation can be changed. By default, FORD documentation comes after whatever it is that you are documenting, either at the end of the line or on a subsequent line. This was chosen because it was felt it is easier to make your documentation readable from within the source-code this way. This

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

looks better/more readable than

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

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

in the opinion of this author, especially with regards to the list of arguments. Since version 1.0.0 it is now possible to place documentation before the code which it is documenting. To do so, specify in the meta-data of your project file predocmark: > (or whatever it is you want to use to indicate preceding documentation). In the first line of your preceding documentation, use !> rather than the usual !!. This can be used on all lines of the preceding documentation if desired, but this is not necessary.

Please note that legacy Fortran (fixed-form code) is not supported at this time. If anyone would like to contribute the necessary modifications to ./ford/reader.py to convert fixed-form syntax into free-form, it should not be difficult (see the approach taken by f90doc). However, it is not a priority for me right now (since I regard fixed-form Fortran as an abomination which should be wiped from the face of this Earth).

Markdown

All documentation, both that provided within the source files and that given in the project file, should be written in Markdown. In addition to the standard Markdown syntax, you can use all of the features in Python's Markdown Extra. Other Markdown extensions automatically loaded are CodeHilite which will provide syntax highlighting for any code fragments you place in your documentation and Meta-Data. The latter is used internally as a way for the user to provide extra information to and/or customize the behaviour of FORD (see Documentation Meta-Data). Information on providing meta-data and what types of data FORD will look for can be found in the next section.

LateX Support

You can insert LaTeX into your documentation, which will be rendered by MathJax. Inline math is designated by \( … \), math displayed on its own line is indicated by $$ … $$ or \[ … \], and a numbered equation is designated by \begin{equation} … \end{equation}. Inline math will not be displayed with the traditional $ … $, as there is too much risk that dollar signs used elsewhere will be misinterpreted. You can refer back to number equations as you would in a LaTeX document. For more details on that feature, see the MathJax Documentation.

Special Environments

Much like in Doxygen, you can use a @note environment to place the succeeding documentation into a special boxed paragraph. This syntax may be used at any location in the documentation comment and it will include as the note's contents anything until the end of the paragraph. Other environments which behave the same way are @warning, @todo, and @bug. Note that these designations are case-insensitive (which, as Fortran programmers, we're all used to). If these environments are used within the first paragraph of something's documentation and you do not manually specify a summary, then the environment will be included in the summary of your documentation. If you do not want it included, just place the environment in a new paragraph of its own.

"Include" Capabilities

FORD uses my Markdown-Include extension. The syntax {!file-name.md!} in any of your documentation will be replaced by the contents of file-name.md. This will be the first thing done when processing Markdown, and thus all Markdown syntax within file-name.md will be processed correctly. You can nest these include statments as many times as you like. All file paths are evaluated relative to the directory containing the project file, unless set to do otherwise.

Macros

FORD features two macros to make it easier to provide intradocumentation links. These are |url| which gets replaced by the project URL, and |media|, which gets replaced by the (absolute) path to the media directory in the output.