The MHKiT documentation is developed as restructured text files that are compiled by Sphinx into html files and then uploaded to the MHKiT Documentation Repository. Using Sphinx, GitHub renders the documentation on the MHKiT Documentation Repository as the MHKiT Documentation Website. This guide will help the user to download the documentation, modify the documentation, build the documentation locally, and push changes back up to the repository.
To update the MHKiT documentation you will need Python 3.6+, Git, Sphinx, and a GitHub account. This documentation assumes the user has a working version of Python installed (We recommend Anaconda Python, during installation check the add Python to Path) and a GitHub account but will cover the needed Python Sphinx package installation.
git clone https://github.com/USERNAME/REPOSITORYNAME.gitOnce cloned use the command line to change directories into the folder created by the clone to update the MHKiT-Python and MHKiT-MATLAB [submodules].
cd MHKiT
git submodule init
git submodule update --remoteThe MHKiT-Python and MHKiT-MATLAB folders should now contain source code.
To build the Python API documentation for submitting a pull request you will want to use the submodule MHKiT-Python included here. To do so first uninstall any MHKiT you may have and then use the python package manager to install this MHKiT submodule.
pip uninstall mhkit
cd MHKiT-Python
pip install -e .NOTE: After building the documentation (see below) be sure to reinstall your MHKiT-Python distribution from pypi (e.g. pip install mhkit) or from your fork of the repository as an editable package (e.g. pip install -e /path/to/my/fork/of/MHKiT-Python)
Sphinx is a python package used to create the MHKiT documentation.
Install Sphinx from the command line NOTE: You may need to add PROXY settings (see info here)
pip install -U Sphinx
Use the command line to install the needed Sphinx submodules (BibTex, MATLAB theme, rtd theme, and NB Sphinx)
pip install -U sphinxcontrib-bibtex sphinxcontrib-matlabdomain sphinx_rtd_theme nbsphinx
nbsphinx --> Version: 0.7.1
sphinxcontrib-matlabdomain --> Version: 0.11.2
sphinxcontrib-bibtex --> Version: 1.0.0
sphinx-rtd-theme --> Version: 0.5.0
You are now ready to begin modifying and building the MHKiT documentation.
/MHKiT/docs/source directory (Check the Sphinx Website for information about the folder structure).git branch featureBranchName
git checkout featureBranchName.rst extension, e.g. index.rst)./MHKiT/docs folder then make html
cd docs
make clean
make htmlUsing your machine's file explorer navigate to MHKiT/docs and use an Internet browser (i.e. Chrome, Safari, Edge, etc. ) to open index.html to view modifications to the documentation source made above.
Once changes have been made the user can push the changes back up to their fork
git statusgit add --all otherwise use git add fileName where fileName is either the file or a list of space-separated files the user wishes to add.git commit -m 'A descriptive message here describing why or what was changed in the documentation'yourFork) feature branch (featureBranchName).
git push -u yourFork featureBranchNamegit push git submodule init git submodule update --remote, refer to https://git-scm.com/book/en/v2/Git-Tools-Submodules for more informationmake clean and then make html*.m or *.py syntax to refer to file extensioninsert code to reference code#### with overline======------^^^^^^""""""++++++