Setup

Reference repository that has been the basis of my structure

• opencobra
• keras

Sphinx

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

1. Modified source/conf.py 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

Github

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

% 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

Maintenance

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

cd docs/build
git clone https://lsy3@github.com/gait-tech/gaittoolbox.git 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.

OpenProject

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

Evernote: https://www.evernote.com/l/ARJQYOPw335Or4YirqVRSeJ80rasQ-Xbgik/

Onedrive: https://unsw-my.sharepoint.com/:f:/r/personal/z5151460_ad_unsw_edu_au/Documents/Thesis%20-%20Sparse%20Mocap/Goal01b-CKFDist/Analysis-ckfdistv1-explore-20200109?csf=1&e=xdOKKq