Contributing Guide

One of the best ways to contribute is by improving our documentation. This project uses sphinx <https://www.sphinx-doc.org/en/master/tutorial/narrative-documentation.html> as a documentor, and specific details for the Matlab Domain are given here: <https://github.com/sphinx-contrib/matlabdomain>

More resources on documentation: https://www.writethedocs.org/guide/

docstrings

The easiest and most effective way to start contributing to the user manual and documentation of the project is by helping improve our docstrings, these are the comments just below the function signature in Matlab before the function content. Here is a simple example in matlab:

function [res] = my_sum(a, b)
% returns the sum of a and b
%
% :param a: first argument to sum
% :param b: second argument to sum
%
% :return: res: the result
end

These commented lines will be exported and make up the documentation for the function “my_sum”

Adding new pages to the user manual

Contributing other pages to the manual requires two steps:

  1. Create a new text file with the file extension “.rst” in the LCD-CT/docs/source folder.

  2. Add the filename without the extension to docs/source/index.rst, specifically adding to the list under “toctree”. For example, after creating a new manual page called “my_new_doc_page.rst”, the list item under toctree would be the following:

    toctree:

    usage

    api

    my_new_doc_page

Writting rst files

reStructuredText is mostly plain text with a few special rules for defining headers and cross-references. Like Markdown, it is a common format for writing technical documentation for software. “rst” stands for reStructuredText. The content in the docstrings after the comment symbol “%” is also written in rst format.

For examples of how to write rst files, you can use look at the raw source of this page. More complete references on writing rst files and code documentation can be found here: