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
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
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
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