Fix warnings in documentation build (#80)

* use sphinxcontrib-googleanalytics * add pandoc to installation instructions * standardize module overview sections and add a template to the readme * add acoustics example to example section, call out IEC 62600-40 in acoustics.rst * fix internal reference in matlab_installation.rst * create a notebook gallery and fix notebook toctree warning * fix webinar.rst indentation * anonymous references in overview.rst * ipython to install instructions to fix lexer issue * update utils API * fix utils API warnings * update mooring API * update loads API * format power API * format qc API * format river API * format tidal API * format tidal API - possible solution for duplicate API warnings * format wave API * remove tidal api comments that caused issues * format acoustics API * consolidate acoustics API description * make references in examples.rst anonymous * update api formatting and functions in all but dolfyn * fix minor typo in conf.py * update dolfyn api format * suppress additional docutils warnings for now * fix typo in mhkit-matlab/api.dolfyn.rst * update reference to nose test to pytest * update MATLAB API * fix some tables in the matlab api * change one reference from MHKiT-Python/master to main
MHKiT-Software · Dec 18, 2024 · 85fac6d · 85fac6d
1 parent d6123d4
commit 85fac6d
Show file tree

Hide file tree

Showing 35 changed files with 912 additions and 862 deletions.
diff --git a/README.md b/README.md
@@ -40,19 +40,23 @@ To update the MHKiT documentation you will need Python 3.6+, Git, Sphinx, and a
 
     ```pip install -U Sphinx```
 
-    - Sphinx --> Version: 3.1.1
+    - Sphinx --> Version: 8.1.3
 
-  - Use the command line to install the needed Sphinx submodules (BibTex, MATLAB theme, rtd theme, and NB Sphinx)
+  - Use the command line to install the needed Sphinx submodules (BibTex, MATLAB theme, rtd theme, NB Sphinx, and google analytics) and additional dependencies
 
-     ```pip install -U sphinxcontrib-bibtex sphinxcontrib-matlabdomain sphinx_rtd_theme nbsphinx```
+     ```pip install -U sphinxcontrib-bibtex sphinxcontrib-matlabdomain sphinx_rtd_theme nbsphinx sphinxcontrib-googleanalytics ipython```
 
-      - nbsphinx  --> Version: 0.7.1
+      - nbsphinx  --> Version: 0.9.5
 
-      - sphinxcontrib-matlabdomain  --> Version: 0.11.2 
+      - sphinxcontrib-matlabdomain  --> Version: 0.22.1
 
-      - sphinxcontrib-bibtex --> Version: 1.0.0
+      - sphinxcontrib-bibtex --> Version: 2.6.3
 
-      - sphinx-rtd-theme --> Version: 0.5.0
+      - sphinx-rtd-theme --> Version: 3.0.2
+
+      - sphinxcontrib-googleanalytics  --> Version: 0.4
+
+    ```conda install pandoc```
 
 You are now ready to begin modifying and building the MHKiT documentation.
 
@@ -130,3 +134,39 @@ Using your machine's file explorer navigate to MHKiT/docs and use an Internet br
   - MHKiT-MATLAB (MHKiT-MATLAB when referring to the repo)
   - MHKiT (Marine and Hydrokinetic Toolkit)
 
+## Modules Template
+All modules in MHKiT should be briefly described in the "Module Overview" Section.
+Below is a template that can be used for a new MHKiT module (fix title 
+characters when adding a section):
+
+NAME Module
+<br />====================
+
+Brief description of what the module dose.
+
+API Documentation
+<br />--------------------
+
+- `Python NAME API Documentation <mhkit-python/api.NAME.html>`_
+- `MATLAB NAME API Documentation <mhkit-matlab/api.NAME.html>`_
+
+Examples
+<br />--------------
+
+- Bulleted list of linked examples
+- pertaining to this module.
+- Tag modules in docs/source/examples.rst as appropriate.
+
+Submodules
+<br />--------------
+
+The NAME module contains the following submodules:
+
+* ``SUBMODULE_NAME``: one sentence description of the submodule. Calculations are based on `IEC TS XXXXX-XXX:20XX EDX <LINK>`
+* ``SUBMODULE_NAME``: etc...
+
+IEC/TS XXXXX-XXX
+<br />---------------------------
+
+Recommends proper use of the module per relevant IEC standards.
+
diff --git a/docs/source/acoustics.rst b/docs/source/acoustics.rst
@@ -2,7 +2,7 @@
 
 Passive Acoustics Module
 ========================
-The acoustics module contains a set of functions to injest hydrophone *.wav* files.
+The acoustics module contains a set of functions to ingest hydrophone *.wav* files.
 Only available in MHKiT-Python in v0.9 or later.
 
 API Documentation
@@ -15,10 +15,11 @@ Examples
 
 - `Passive Acoustics Example <acoustics_example.ipynb>`_
 
+Submodules
+--------------
 The acoustics module contains the following submodules:
 
 * ``io``: Contains functions to read and output *.wav* files
-* ``analysis``: Contains functions to process, clean and analyze passive acoustics data
+* ``analysis``: Contains functions to process, clean and analyze passive acoustics data. 
+  Calculations are based on `IEC TS 62600-40:2019 ED1 <https://webstore.iec.ch/publication/31031>`_.
 * ``graphics``: Contains functions to plot spectral data
-
-See :ref:`MHKiT-Python <python>`  for more details on the acoustics module.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -28,15 +28,16 @@
     'sphinx_rtd_theme',
     'nbsphinx',
     'sphinxcontrib.bibtex',
-    'sphinxcontrib.matlab',       
+    'sphinxcontrib.matlab',      
+    'sphinxcontrib.googleanalytics', 
 ]
 
 autosectionlabel_prefix_document = True
 
 #    
 
 # -- Path setup --------------------------------------------------------------
-# If extensions (or modules to document with autodoc) are in another dire	ctory,
+# If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
@@ -105,6 +106,11 @@
 # can be set to alphabetical, groupwise or bysource
 autodoc_member_order = 'bysource'
 
+# A list of warning codes to suppress arbitrary warning messages.
+suppress_warnings = [
+    'docutils',  # duplicate object description, unexpected indentation
+]
+
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 #default_role = None
@@ -148,7 +154,8 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 # Added Google Analytics to theme based on https://github.com/readthedocs/sphinx_rtd_theme/pull/411
-html_theme_options = {'analytics_id': 'UA-164358105-1'}
+googleanalytics_id = 'UA-164358105-1'
+googleanalytics_enabled = True
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []

diff --git a/docs/source/contact.rst b/docs/source/contact.rst
@@ -26,7 +26,7 @@ To propose changes to the MHKiT software, complete your development on a distinc
 Submit a `pull request <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request>`_ of the modified repository into the appropriate repository's ``develop`` branch.
 If an update contains a bug fix, create the pull request into the ``develop`` branch.
 Once reviewed by the MHKiT development team, pull requests will be merged into MHKiT. 
-Features will later be merged into the master branch and included in future releases of MHKiT.
+Features will later be merged into the main branch and included in future releases of MHKiT.
 Software developers, within the MHKiT development team and external collaborators, are expected to follow standard software quality practices. In any PR, please include documentation and tests for new code. Create an additional PR into the MHKiT documentation repository as needed.
 
 

diff --git a/docs/source/dolfyn.rst b/docs/source/dolfyn.rst
@@ -16,6 +16,8 @@ Examples
 - `ADV Example <adv_example.ipynb>`_
 - `Python Tanana River Resource Characterization <ADCP_Delft3D_TRTS_example.ipynb>`_
 
+Submodules
+--------------
 The dolfyn module contains the following submodules:
 
 * ``adp``: Contains functions to process, clean and analyze ADCP data
@@ -24,5 +26,3 @@ The dolfyn module contains the following submodules:
 * ``rotate``: Contains tools to rotate a dataset to a new coordinate system. 
 * ``time``: Contains functions to modify the format of the stored time between a variety of time formats.
 * ``tools``: Contains miscellaneous functions used in mhkit that may prove useful to users
-
-See :ref:`MHKiT-Python <python>`  for more details on the Dolfyn module.
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -3,6 +3,9 @@
 Examples
 ========
 
+Overview
+---------
+
 This page details all the available examples of MHKiT functions and features.
 Python examples are available as Jupyter notebooks and MATLAB examples as live scripts.
 Not all MATLAB examples are available yet but are coming soon.
@@ -32,7 +35,6 @@ Search for the following tags to identify relevant examples:
    * - qc
      - Examples preparing data, doing quality control, etc
 
-
 .. list-table::
    :header-rows: 1
 
@@ -42,127 +44,143 @@ Search for the following tags to identify relevant examples:
      - Description
      - Tags
    * - Quality Control
-     - `Notebook <qc_example.ipynb>`_
-     - `Live Script <mhkit-matlab/qc_example.html>`_
+     - `Notebook <qc_example.ipynb>`__
+     - `Live Script <mhkit-matlab/qc_example.html>`__
      - Data quality control workflow example
      - qc
    * - River Example
-     - `Notebook <river_example.ipynb>`_
-     - `Live Script <mhkit-matlab/river_example.html>`_
+     - `Notebook <river_example.ipynb>`__
+     - `Live Script <mhkit-matlab/river_example.html>`__
      - Visualize river current energy from USGS data
      - current, resource, iec
    * - Tidal Example
-     - `Notebook <tidal_example.ipynb>`_
+     - `Notebook <tidal_example.ipynb>`__
      - Coming soon
      - Visualize velocity duration curve from NOAA tidal data
      - current, resource, iec
    * - Tidal Power Performance Example
-     - `Notebook <tidal_performance_example.ipynb>`_
-     - `Live Script <mhkit-matlab/tidal_example.html>`_
+     - `Notebook <tidal_performance_example.ipynb>`__
+     - `Live Script <mhkit-matlab/tidal_example.html>`__
      - Tidal power performance testing workflow
      - current, iec
    * - ADCP Example
-     - `Notebook <adcp_example.ipynb>`_
+     - `Notebook <adcp_example.ipynb>`__
      - Coming soon
      - Acoustic Doppler Current Profiler (ADCP) analysis workflow
      - current, resource
    * - ADV Example
-     - `Notebook <adv_example.ipynb>`_
+     - `Notebook <adv_example.ipynb>`__
      - Coming soon
      - Acoustic Doppler Velocimetry (ADV) analysis workflow
      - current, resource
    * - Tanana River Resource Characterization
-     - `Notebook <ADCP_Delft3D_TRTS_example.ipynb>`_
+     - `Notebook <ADCP_Delft3D_TRTS_example.ipynb>`__
      - Coming soon
      - Site-specific river resource characterization
      - current, resource
    * - Delft3D
-     - `Notebook <Delft3D_example.ipynb>`_
-     - `Live Script <mhkit-matlab/delft3d_example.html>`_
+     - `Notebook <Delft3D_example.ipynb>`__
+     - `Live Script <mhkit-matlab/delft3d_example.html>`__
      - Analyze and visualize output from Delft3D
      - current, resource
    * - WEC Power Performance
-     - `Notebook <wave_example.ipynb>`_
-     - `Live Script <mhkit-matlab/wave_example.html>`_
+     - `Notebook <wave_example.ipynb>`__
+     - `Live Script <mhkit-matlab/wave_example.html>`__
      - Visualize WEC Power vs. Wave Resource
      - wave, resource, iec
    * - Directional Waves Analysis
-     - `Notebook <directional_waves.ipynb>`_
+     - `Notebook <directional_waves.ipynb>`__
      - Coming soon
      - Visualize directional wave energy spectra from NDBC data
      - wave, resource
    * - Environmental Contours
-     - `Notebook <environmental_contours_example.ipynb>`_
-     - `Live Script <mhkit-matlab/environmental_contours_example.html>`_
+     - `Notebook <environmental_contours_example.ipynb>`__
+     - `Live Script <mhkit-matlab/environmental_contours_example.html>`__
      - Visualize estimates of extreme sea states
      - wave, resource
    * - PacWave Resource Characterization
-     - `Notebook <PacWave_resource_characterization_example.ipynb>`_
+     - `Notebook <PacWave_resource_characterization_example.ipynb>`__
      - Coming soon
      - Site-specific resource characterization using NDBC data
      - wave, resource, iec
    * - CDIP
-     - `Notebook <cdip_example.ipynb>`_
-     - `Live Script <mhkit-matlab/cdip_example.html>`_
+     - `Notebook <cdip_example.ipynb>`__
+     - `Live Script <mhkit-matlab/cdip_example.html>`__
      - Download and visualize CDIP resource data
      - wave, resource
    * - WEC-Sim
-     - `Notebook <wecsim_example.ipynb>`_
-     - `Live Script <mhkit-matlab/wecsim_example.html>`_
+     - `Notebook <wecsim_example.ipynb>`__
+     - `Live Script <mhkit-matlab/wecsim_example.html>`__
      - Visualize output from WEC-Sim
      - wave
    * - SWAN
-     - `Notebook <SWAN_example.ipynb>`_
-     - `Live Script <mhkit-matlab/SWAN_example.html>`_
+     - `Notebook <SWAN_example.ipynb>`__
+     - `Live Script <mhkit-matlab/SWAN_example.html>`__
      - Visualize output from Simulating Waves Nearshore (SWAN)
      - wave
    * - WPTO Hindcast
-     - `Notebook <WPTO_hindcast_example.ipynb>`_
-     - `Live Script <mhkit-matlab/WPTO_hindcast_example.html>`_
+     - `Notebook <WPTO_hindcast_example.ipynb>`__
+     - `Live Script <mhkit-matlab/WPTO_hindcast_example.html>`__
      - Download and visualize WPTO Hindcast data
      - wave, resource
    * - Metocean Analysis
-     - `Notebook <metocean_example.ipynb>`_
+     - `Notebook <metocean_example.ipynb>`__
      - Coming soon
      - Download and visualize NDBC metocean data
      - wave, resource
    * - Upcrossing Analysis
-     - `Notebook <upcrossing_example.ipynb>`_
+     - `Notebook <upcrossing_example.ipynb>`__
      - Coming soon
      - Analyze the surface elevation of a wave
      - wave
    * - Loads Analysis
-     - `Notebook <loads_example.ipynb>`_
-     - `Live Script <mhkit-matlab/loads_example.html>`_
+     - `Notebook <loads_example.ipynb>`__
+     - `Live Script <mhkit-matlab/loads_example.html>`__
      - Compute structural loads quantities of interest
      - loads
    * - Extreme Response MLER
-     - `Notebook <extreme_response_MLER_example.ipynb>`_
-     - `Live Script <mhkit-matlab/extreme_response_MLER_example.html>`_
+     - `Notebook <extreme_response_MLER_example.ipynb>`__
+     - `Live Script <mhkit-matlab/extreme_response_MLER_example.html>`__
      - Extreme conditions model - Most Likely Extreme Response (MLER)
      - loads, wave
    * - Extreme Response Contour
-     - `Notebook <extreme_response_contour_example.ipynb>`_
-     - `Live Script <mhkit-matlab/extreme_response_contour_example.html>`_
+     - `Notebook <extreme_response_contour_example.ipynb>`__
+     - `Live Script <mhkit-matlab/extreme_response_contour_example.html>`__
      - Extreme conditions model - contour approach
      - loads, wave
    * - Extreme Response Full Sea State
-     - `Notebook <extreme_response_full_sea_state_example.ipynb>`_
-     - `Live Script <mhkit-matlab/extreme_response_full_sea_state_example.html>`_
+     - `Notebook <extreme_response_full_sea_state_example.ipynb>`__
+     - `Live Script <mhkit-matlab/extreme_response_full_sea_state_example.html>`__
      - Extreme conditions model - full sea state approach
      - loads, wave
    * - Short-Term Extremes
-     - `Notebook <short_term_extremes_example.ipynb>`_
-     - `Live Script <mhkit-matlab/short_term_extremes_example.html>`_
+     - `Notebook <short_term_extremes_example.ipynb>`__
+     - `Live Script <mhkit-matlab/short_term_extremes_example.html>`__
      - Visualize probability distribution of short-term time series data
      - loads, wave
    * - Electrical Power Analysis
-     - `Notebook <power_example.ipynb>`_
-     - `Live Script <mhkit-matlab/power_example.html>`_
+     - `Notebook <power_example.ipynb>`__
+     - `Live Script <mhkit-matlab/power_example.html>`__
      - Compute 3-phase power quantities of interest
      - power, iec
    * - Mooring
-     - `Notebook <mooring_example.ipynb>`_
+     - `Notebook <mooring_example.ipynb>`__
      - Coming soon
      - Visualize and analyze output from MoorDyn
      - mooring, wave
+   * - Acoustics
+     - `Notebook <acoustics_example.ipynb>`__
+     - Coming soon
+     - Ingest, analyze and visualize passive acoustic output
+     - acoustics, iec
+
+All Python Notebooks
+---------------------
+.. doesn't work for LiveScripts because nbgallery is inherently for notebooks. 
+.. Automatically makes a table of notebook names/icons and adds them to the toctree
+.. nbgallery::
+   :name: example_gallery_python
+   :glob:
+
+   *_example
+   directional_waves
diff --git a/docs/source/loads.rst b/docs/source/loads.rst
@@ -18,11 +18,10 @@ Examples
 
   Calculations are based on `IEC TS 62600-3:2020 ED1 <https://webstore.iec.ch/publication/60359>`_ .
 
+Submodules
+--------------
 The loads module contains the following submodules:
 
 * ``general``: Computes loads metrics such as damage equivalent loads.
 * ``graphics``: Generates graphics of loads statistics.
 * ``extreme``: Contains functions to calculate peak distribution.
-
-See :ref:`MHKiT-Python <python>` or :ref:`MHKiT-MATLAB <matlab>` for more details on the loads module.
-
diff --git a/docs/source/matlab_installation.rst b/docs/source/matlab_installation.rst
@@ -6,7 +6,7 @@ MHKiT-MATLAB Installation
 The following section includes instructions for installing `MHKiT-MATLAB <https://github.com/MHKiT-Software/MHKiT-MATLAB>`_ .
 
 * New users should follow the :ref:`Installation Steps <installation-section>`.
-* Experienced users can follow the :ref:`Advanced Installation Steps <advanced-installation-section>`.
+* Experienced users can follow the :ref:`Advanced Installation Steps <matlab-advanced-installation-section>`.
 
 
 Installation Overview