How to Update the MHKiT Website

Requirements

• Follow MHKiT Installation steps, including the MHKiT-Python and Requirements headers.

Download/Install Required Packages

Step 1. Download/Install Sphinx package and extensions

• Install Sphinx from cmd pip install -U Sphinx (more info here)

• Install BibTex, MATLAB theme, rtd theme, NB Sphinx, NB Sphinx Link, Goggle Analytics by running the following code pip install -U sphinxcontrib-bibtex sphinxcontrib-matlabdomain sphinx_rtd_theme nbsphinx nbsphinx_link googleanalytics (more info on Google Analytics here)

• NOTE: You may need to add PROXY settings (see info here)

Step 2. Git Documents and submodules

• In order to update the documentation, fork the MHKiT your own repository
• Update the MHKiT-Python and MHKiT-MATLAB submodules using git submodule init and git submodule update --remote, refer to https://git-scm.com/book/en/v2/Git-Tools-Submodules for more information

Update the MHKiT Website

The MHKiT documentation located on the MHKiT Documentation Repository, referred to as $docs. The documentation is developed as restructured text files that are compiled by Sphinx into html files. To edit the documentation, first verify that the most recent versions of MHKiT-Python and MHKiT-MATLAB are in your local $MHKiT-master/. Then modify the source files located in the $docs/source directory using the syntax described on the Sphinx Website. Once you are done editing, cd to your local $docs directory from cmd, clean the previous compile with make clean, and compile the updated the documentation withmake html. This compiles an html version of the website in $docs/. After compiling the updated website, you can view the local copy of the website by opening the $docs/index.html file from your local directory, and viewing it in a web browser (before pushing it online).

Best Practices

• Run spell check (not built into most text editors)
• Update the MHKiT-Python and MHKiT-MATLAB submodules git submodule init git submodule update --remote, refer to https://git-scm.com/book/en/v2/Git-Tools-Submodules for more information
• When compiling the website, make clean and then make html

Formatting Guidelines

• *.m or *.py syntax to refer to file extension
• use insert code to reference code
• use API documentation from source code
• Title #### with overline
• Heading 1 ======
• Heading 2 ------
• Heading 3 ^^^^^^
• Heading 4 """"""
• Made sure header underline is for full length of header text
• Use this style guide: https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html

Terminology Guidelines

• DataFrame (not dataframe)
• MATLAB (not Matlab)
• Python (no python)
• pandas (not Pandas)
• MHKiT (not mhkit)
• open-source (not open source)
• time-series (not timeseries or time series)
• time-domain (not time domain)
• frequency-domain (not frequency domain)
• MHKiT-Python (or link to MHKiT-Python when referring to the repo)
• MHKiT-MATLAB (MHKiT-MATLAB when referring to the repo)
• MHKiT (Marine and Hydrokinetic Toolkit)

Unresolved Doc Issues

• 16 warnings
  • 4 .nblink: WARNING: document isn't included in any toctree
  • duplicate object warnings
  • 2 MHKiT-MATLAB formating warnings (listed below)
• MHKiT-MATLAB
  • MATLAB Live examples remove index, and must be exorted as HTML manually
  • mhkit.wave.graphics.plot_spectrum:1: WARNING: Unexpected section title or transition.
  • mhkit.wave.graphics.plot_spectrum:13: WARNING: Unexpected section title or transition
• MHKiT-Python
  • Jupyter Notebooks examples change the index

Push updates to the MHKiT Website

Using Sphinx, GitHub renders the documentation on the MHKiT Documetnation Repository as the MHKiT Website. The user then pushes changes in the html documentation directly to the MHKiT Documetnation Repository, by doing the following:

# Move to the local $docs directory in cmd
cd $docs

# Clean and build the html documentation in cmd
make clean
make html

# Use Git-shell to check status of the MHKiT documentation respository, then commit and push changes.
git status
git add --all
git commit -m 'update to MHKiT documentation'
git push