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.
- Install sphinx
pip install -U sphinxcontrib-matlabdomain
- Create a docs directory and cd into this directory.
mkdir docs cd docs
- Setup Sphinx using command
source/conf.pyaccording 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']
- Install theme similar to readthedocs.
pip install sphinx_rtd_theme
- See docstring tutorial on how to add documentation inside your code
- 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
- When using the first time
git submodule update --init --recursive
- 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
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
- Run sphinx html build
- Commit and push
git commit -a -m "init gh pages" git push --set-upstream origin gh-pages
- For newly cloned repository, pull html code at docs/build
cd docs/build git clone https://firstname.lastname@example.org/gait-tech/gaittoolbox.git html --branch gh-pages
- Generate sphinx html using the command (from root)
cd docs make html
- From the directory
docs/build, commit and push gh-pages branch
cd docs/build/html git commit -a -m "<some message>" git push
- 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 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