PhD code documentation


Reference repository that has been the basis of my structure


The code documentation was done using sphinx. Initially I planned on using doxygen but decided to shift to sphinx as it supports html, latex, and pdf generation superbly. For comparison between the two, see link. readthedocs uses sphinx.

Sphinx was setup-ed for my github Matlab code based on the following references: medium article

  1. Install sphinx

    pip install -U sphinxcontrib-matlabdomain
  2. Create a docs directory and cd into this directory.

    mkdir docs
    cd docs
  3. Setup Sphinx using command

    Sphinx quickstart configuration
  4. Modified source/ according to link. Note: the matlabdomain extension should be added to the end to make sure it runs and dependencies are loaded first.

    # tell Sphinx matlab extension where to find matlab code.
    matlab_src_dir = os.path.abspath(os.path.join('..', '..'))
    # add to extension
    extensions = ['sphinxcontrib.matlab', 'sphinx.ext.autodoc']
  5. Install theme similar to readthedocs.

    pip install sphinx_rtd_theme
  6. See docstring tutorial on how to add documentation inside your code


  1. Paper code and library are set up as separate repositories. To update the paper repo from the gaittoolbox repo use

    git submodule update --remote --merge
  2. When using the first time

    git submodule update --init --recursive

Github Pages

  1. Follow the instructions at link, specifically the one under subsection Set up sphinx within main repository and Set up separate docs repository. See command dump below. A point of difference is instead of setting up the html directory outside the project, I just used the html folder inside the repository. To prevent branch conflict, I also added docs/build/* to .gitignore.

    mkdir <repo>/docs
    cd docs
    % To simplify setup, make sure html folder is empty
    cd html 
    git branch gh-pages
    git symbolic-ref HEAD refs/heads/gh-pages  # auto-switches branches to gh-pages
    rm .git/index
    git clean -fdx


  1. For newly cloned repository, pull html code at docs/build

    cd docs/build
    git clone html --branch gh-pages
  2. Generate sphinx html using the command (from root)

    cd docs
    make html
  3. From the directory docs/build, commit and push gh-pages branch

    cd docs/build/html
    git commit -a -m "<some message>"
    git push
  4. In the unlikely event of conflict when pulling gh-pages, just rebuild the html. The files that needs to be merged will automatically be set equal to the most recent version locally. Commit them accordingly.


Add the following description to each analysis. +paper revision: commit a1a1df00ff64c30b1f33065576b567ad9b0002fd (HEAD -> dev, origin/dev)

gaittools revision: commit e83c1844bc1ee0a883e02f60a8cb62406840a350 (HEAD -> lgcekf-7seg, origin/lgcekf-7seg)

exploreUNSW dataarchive: output-ckfdistv1-explore


Luke Sy
PhD Candidate

My research interests include state estimation, robotics, wearable sensors, machine learning, and biomedical engineering.