Fix warnings in documentation build

[akeeste]

This PR attempts to fix the plethora of warnings that appear in our current documentation build. Not all of them are critical but the vast number of warnings makes it very difficult to see if a PR is building successfully or introducing warnings.

I will note the various problems and solutions. Hopefully this can help future users building sphinx documentation here or elsewhere:

error / error message --> solution

• [x] pygments lexer name 'ipython3' is not known --> pip install ipython in the build steps
• [x] python and matlab references missing --> remove references, these sections were removed previously
• [x] X document is not included in the toctree --> using nbgallery to showcase examples in icons and add them to the toctree at the same time
• [x] depreciation of current method for google analytics --> use sphinxcontrib-googleanalytics
• [x] pandoc error with examples --> conda install pandoc in the build steps
• [x] duplicate explicit target name --> this could be an internal reference that is duplicated, but is typically an external URL that creates a named reference. Make targets for links anonymous: `Title <link>`__ (that's TWO underscores for an anonymous reference)
• [x] WARNING: image file not readable: PATH/FILENAME.png [image.not_readable] --> resolved in source, see separate comment below
• [ ] :XX: SyntaxWarning: invalid escape sequence '\s' --> might be coming from a graphics API, e.g.
• [ ] docstring indentation issues in source code --> hopefully future linting catches these. There are many and the exact problems end up very ambiguous.
• [ ] docstring of mhkit.river.performance.power_coefficient:1: WARNING: duplicate object description of mhkit.river.performance.power_coefficient, other instance in MHKiT\docs\source\mhkit-matlab\api.river.rst, use :noindex: for one of them [docutils]
• [x] API formatting issues --> I will standardize the formatting for the API documentation across modules and create a template for new modules
• [x] inline emphasis start-string without end-string --> occurs in the swan example due to the text "*.mat files". Single escape chars () work in markdown for the notebook but still throw a sphinx warning. Double escape chars (\) result in one showing up in the markdown of the notebook but removes the sphinx warning. There should be an easy solution to typing an asterisk but apparently is not. Super annoying. Perhaps to do with nbsphinx converting notebooks. Making that line code for now as that seems to work
• [ ] html_static_path entry '_static' is placed inside outdir --> ?

[akeeste]

Notes on the warning "image file not readable": this is an issue related to how nbsphinx is processing markdown output and converting it into html. Currently the TRTS and Strain examples have local images in examples/data/ linked in the jupyter notebooks using HTML: <img src="data/river/ADCP_transect/TRTS_transect_map.png" width=1080 height=920 />

The images are missing in the end HTML because:

1. the image files are not being copied from mhkit-python/examples/data into a directory in the docs build and
2. for the local images linked with HTML in the notebooks, the path to the image is taken as is. The path to the image is not updated in the built HTML (for example in docs/strain_measurement_example.html). The path to the image should be updated based on where those files would be copied to, such as docs/_images

• the same issue occurs when using markdown instead of html to link to the local images

Per the nbsphinx docs this should be straight forward, but the processing of certain markdown features through nbsphinx seems to be a known issue. https://github.com/spatialaudio/nbsphinx/pull/438 https://github.com/spatialaudio/nbsphinx/issues/36 https://github.com/spatialaudio/nbsphinx/issues/49

Solution: embedding the images as an attachment in the notebook seems to work. I'll take this approach to solve this warning.