Skip to content

How to write documentation

All documentation is written in an extended Markdown markup language. TokSys documentation is created using the MkDocs static site generator with the MkDocs-Material theme which has extended Markdown capabilities.

Installing Documentation Dependencies

pip install mkdocs
pip install pymdown-extensions
pip install mkdocs-material
pip install mkdocs-material-extensions
conda config --add channels conda-forge
conda config --set channel_priority strict
conda install mkdocs
conda install pymdown-extensions
conda install mkdocs-material
conda install mkdocs-material-extensions

Documentation Pages

As mentioned, documentation pages are written in an extended Markdown. MkDocs parses Markdown files contained in the docs directory. To create a new documenation page just make a new Markdown file in the docs directory and MkDocs will transform it into valid HTML. For example, the markdown file for this page is located at docs/tutorials/documentation.md.

Note

The documentation page title is taken from the first Markdown header in the file and not the name of the file.

Function and Script Documentation

Documentation can be written along side code. For example:

function c = add(a,b)
%  SYNTAX:  c = add(a,b)
%
%  PURPOSE:  Add two numbers
%
%  INPUT:
%       a, b  = two numbers
%
%  OUTPUT:
%       c = sum of a and b

%+## Extra Markdown
%+
%+Here is some extra information that might be useful
%+
%+\begin{equation}
%+    c = a + b
%+\end{equation}
%+
%+!!! warning "Deprecated"
%+    This function has been deprecated. Please use the built in + operator

% Regular code follows
def add(a,b):
#  SYNTAX:  c = add(a,b)
#
#  PURPOSE:  Add two numbers
#
#  INPUT:
#       a, b  = two numbers
#
#  OUTPUT:
#       c = sum of a and b

#+## Extra Markdown
#+
#+Here is some extra information that might be useful
#+
#+\begin{equation}
#+    c = a + b
#+\end{equation}
#+
#+!!! warning "Deprecated"
#+    This function has been deprecated. Please use the built in + operator

# Regular code follows
int add(int a,int b) {
//  SYNTAX:  c = add(a,b)
//
//  PURPOSE:  Add two numbers
//
//  INPUT:
//       a, b  = two numbers
//
//  OUTPUT:
//       c = sum of a and b

//+## Extra Markdown
//+
//+Here is some extra information that might be useful
//+
//+\begin{equation}
//+    c = a + b
//+\end{equation}
//+
//+!!! warning "Deprecated"
//+    This function has been deprecated. Please use the built in + operator

// Regular code follows
real function add(a, b) result (c)
C  SYNTAX:  c = add(a,b)
C
C  PURPOSE:  Add two numbers
C
C  INPUT:
C       a, b  = two numbers
C
C  OUTPUT:
C       c = sum of a and b

C+## Extra Markdown
C+
C+Here is some extra information that might be useful
C+
C+\begin{equation}
C+    c = a + b
C+\end{equation}
C+
C+!!! warning "Deprecated"
C+    This function has been deprecated. Please use the built in + operator

C Regular code follows
real function add(a, b) result (c)
!  SYNTAX:  c = add(a,b)
!
!  PURPOSE:  Add two numbers
!
!  INPUT:
!       a, b  = two numbers
!
!  OUTPUT:
!       c = sum of a and b

!+## Extra Markdown
!+
!+Here is some extra information that might be useful
!+
!+\begin{equation}
!+    c = a + b
!+\end{equation}
!+
!+!!! warning "Deprecated"
!+    This function has been deprecated. Please use the built in + operator

! Regular code follows

Tip

The fields SYNTAX or USAGE, PURPOSE, INPUT, and OUTPUT in the first part of the documentation is recommended

The script create_docs is used to extract the documentation from the source files. The script does two passes over a file. The first pass is to extract the basic information denoted by the first continguous comment block denoted by a single comment mark e.g. % or // depending on the source file. This documentation is interpreted as raw text and is wrapped in a markdown code block.

Note

Matlab documentation denoted by a single % will be displayed when using Matlab's built-in help command

The second pass extracts the contents in the first contiguous comment block denoted denoted with a comment mark and a + sign e.g. %+. This documenation is interpreted as markdown.

The above examples will be rendered as the following:

Example Documentation

Basic Information

  SYNTAX:  c = add(a,b)

  PURPOSE:  Add two numbers

  INPUT:
       a, b  = two numbers

  OUTPUT:
       c = sum of a and b

Extra Markdown

Here is some extra information that might be useful

\[\begin{equation} c = a + b \end{equation}\]

Deprecated

This function has been deprecated. Please use the built in + operator

To extract the inline documentation from the source files run the following in the docs directory

rm -rf function-guide # remove old files
./create_docs ../matlab function-guide
This will create a cooresponding markdown file for every source file in the matlab directory in the docs/function-guide directory with the directory tree mirroring the matlab directory. For example, the documenation in matlab/GAcontrol/bodehz.m gets parsed into a file called docs/function-guide/GAcontrol/bodehz_m.md.

Previewing the Documentation Website

You can create a live preview your documentation by running

mkdocs serve # Creates a live-updating webpage at http://127.0.0.1:8000

Building the Website

You can create the function/script documentation by running

makeit docs
in the TokSys directory. This will pull the documenation from the source files using the create_docs script and build the website fom the Markdown files in the docs directory.

Deploying Website

Todo

Automagically deploy website when pushed to repo