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
  1. Create a docs directory and cd into this directory.
mkdir docs
cd docs
  1. Setup Sphinx using command
Sphinx quickstart configuration
  1. 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']
  1. Install theme similar to readthedocs.
pip install sphinx_rtd_theme
  1. 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
  1. 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
git clone <repo> html
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. Run sphinx html build
  2. Commit and push
git commit -a -m "init gh pages"
git push --set-upstream origin gh-pages


  1. For newly cloned repository, pull html code at docs/build
cd docs/build
git clone html --branch gh-pages
  1. Generate sphinx html using the command (from root)
cd docs
make html
  1. From the directory docs/build, commit and push gh-pages branch
cd docs/build/html
git commit -a -m "<some message>"
git push
  1. 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.