mhkit-software / mhkit Goto Github PK

View Code? Open in Web Editor NEW

4.0 9.0 13.0 208.61 MB

MHKiT Documentation

Home Page: https://MHKiT-Software.github.io/MHKiT/

mhkit mhkit-matlab mhkit-python mhk marine-renewable-energy mhkit-documentation

mhkit's People

Stargazers

Watchers

Forkers

seanpluemer kmruehl rpauly18 ssolson dylanmayes77 kbrode22 ryancoe zzq1019 alex-mcvey kelsonmarine akeeste simmsa anthonygrancagnolo

mhkit's Issues

update package dependencies

update package dependencies for new release

MHKiT does not work on Mac as long as it comes with Python 2.7

Should we say this earlier, under overview, to avoid late disappointment?

River & Tidal modules

"Calculations are based on IEC TS 62600-201:2015 ED1 and IEC TS 62600-301:2019 ED1."
Can we delete -301 on the tidal module and -201 on the river module? Having both may raise questions.

Documentation doesn't compile with Sphinx Version: 3.2.0

Documentation doesn't compile with Sphinx Version: 3.2.0.

Use the following package versions to compile documentation:

Documentation compiles with Sphinx Version: 3.1.1
Other packages requirements listed here: https://github.com/MHKiT-Software/MHKiT/blob/master/README.md

installing via `pip install -e path/to/mhkit`

We need to change the documentation to remove references to python setup.py develop.
It is recommended to pip install these files in editable mode.
pip install -e path/to/MHKiT

Then to switch between MHKiT documentation and a develop version one would

pip uninstall mhkit
pip install -e path/to/otherMHKiT

Originally posted by @ssolson in #15 (comment)

README.md Updates

The description of how to work on the documentation makes sense, even the description of the featureBranch, but the instructions stop short of actually submitting a PR to MHKiT-Software/MHKiT. @ssolson I can take a stab at adding this description, unless you already assigned it to Sean.
Should we have a list of unresolved issues with the Docs in the README? Would it not be better to simply just have Issues on each? @kmruehl

Improvement of installation documentation

1. The link to the Anaconda distribution refers to the anaconda distribution with python 3.8. Meanwhile, MHKiT only works with python 3.6 and 3.7. A link to an anaconda distribution with python 3.6 or 3.7 is needed to replace the current link.

2. The "Check the MATLAB Environment for Python" section recommends skipping to the "Install the MHKiT-MATLAB Toolbox" section if the python version is 3.6+. This statement is highlighted in the red box below

There are two issue with that statement:

First, MHKiT only works with Python 3.6 and 3.7; It does NOT work with 3.8. Instead of "3.6+", the doc should only say that 3.6 and 3.7 are good and all other versions of python are bad - as far as MHKiT is concerned.

Second, The following section is NOT titled "Install the MHKiT-MATLAB Toolbox" section, Instead, it is titled "Install the MHKiT-MATLAB Toolbox (mhkit.mltbx)". Installing the MHKiT-MATLAB toolbox is critical to the operation of the MHKiT package and users often miss that step. While documentation is correct, clarifying the name better might alert users to the importance of the following step.

3. To avoid users skipping the "Install the MHKiT-MATLAB Toolbox (mhkit.mltbx)" step, a screen shot of what the user should see can be added to the documentation. An example of such screen shot is added below:

Index issues for MHKiT-MATLAB and MHKiT-Python examples

The MHKiT examples don't work with index. This is true for both MHKiT-MATLAB examples using MATLAB Live Scripts, and MHKiT-Python examples using Jupyter Notebooks.

MHKiT-MATLAB examples using MATLAB Live Scripts
- HTML is generated by saving the MATLAB Live Script .mlx example files as *.html files
- The MHKiT documentation then points to these *.html files within the MHKiT-MATLAB submodule
- This means the index is removed when you navigate to the MHKiT-MATLAB examples within the documentation.
MHKiT-Python examples using Jupyter Notebooks
- HTML is generated by using the nbsphinx_link extension
- The MHKiT documentation uses *.nblink files to specify the location of the Jupyter Notebook *.ipynp files within the MHKiT-Python submodule
- This means the index stays, but when you navigate to the MHKiT-Python examples within the documentation, but you lose your place in the index.

MHKiT-MATLAB Install Instructions

Need to note in the instructions for installing MHKiT in Matlab that if using an Anaconda environment, Matlab will not utilize any python interpreter outside of the base environment despite all indications that come from Matlab. This seems to be an issue on the Matlab side and it should be able to use different environments but for now I think it would help users to know that this issue exists.

Matlab miniconda installation typo

In step 7 of the MHKiT-Matlab Miniconda instructions, the command for getting the executable should be "python -c ..." not "python -e ...".

Citations seem out of date

The Cite Us page in the documentation seems out of date.

Authors:
- Does it make sense to update the authors to the current contributors of each package?
Abstract Note:
- References to Code Hub should be changed to Software
Year
- How should this be handled? Technically 2020 was the year of inception, but the software has changed significantly between 2020 and the present.

Unresolved Documentation Warnings

16 warnings total (at time of opening issue)

4 *.nblink: WARNING: document isn't included in any toctree duplicate object warnings
duplicate object warnings
MHKiT-MATLAB formatting
- mhkit.wave.graphics.plot_spectrum:1: WARNING: Unexpected section title or transition.
- mhkit.wave.graphics.plot_spectrum:13: WARNING: Unexpected section title or transition

Package Dependencies

@ssolson Is this still the full list of python package dependencies? I thought we added some new ones, like datetime. If it's not the full list, can you provide a full list and I'll update the docs.
https://mhkit-software.github.io/MHKiT/installation.html#requirements

@rpauly18 similar question, and I believe this is still a TBD issue for MHKiT-MATLAB, but do we have any MATLAB toolbox dependencies we should list?
https://mhkit-software.github.io/MHKiT/installation.html#id7

Reading ad2cp-file with dolfyn.read gives completely wrong temperature values

I'm using MHKiT (version 0.7.0) to open an ad2cp-file from Nortek Signature1000 in python, and noticed that the temperature values are completely off. They range between 653.42 and 653.58. Temperature values are normal when I convert the ad2cp-file to a mat-file using Nortek's own software.

Happy to provide more details if needed. Thank you for an overall great software!

Need to update AP Value

This value needs to be updated due to the following issues:
MHKiT-Software/MHKiT-Python#165
MHKiT-Software/MHKiT-Python#236
MHKiT-Software/MHKiT-Python#295

https://github.com/MHKiT-Software/MHKiT/blame/beaa580adee6389d93181ae4cd9886b7b5df429e/docs/source/installation.rst#L94

Documentation build warnings/errors

Below is the current output from make html after running make clean:

make html
sphinx-build -b html -d ./doctrees   source .
Running Sphinx v7.2.6
WARNING: html_static_path entry '_static' is placed inside outdir
loading pickled environment... checking bibtex cache... up to date
done
[autosummary] generating autosummary for: ADCP_Delft3D_TRTS_example.ipynb, Delft3D_example.ipynb, PacWave_resource_characterization_example.ipynb, SWAN_example.ipynb, WPTO_hindcast_example.ipynb, adcp_example.ipynb, adv_example.ipynb, cdip_example.ipynb, citeus.rst, contact.rst, ..., short_term_extremes_example.ipynb, terminology.rst, tidal.rst, tidal_example.ipynb, troubleshooting.rst, utils.rst, wave.rst, wave_example.ipynb, webinars.rst, wecsim_example.ipynb
WARNING: [sphinxcontrib-matlabdomain] Unexpected class attribute: 'TestTags'.  In 'mhkit.tests.Loads_TestLoads'.
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 2 source files that are out of date
updating environment: 0 added, 10 changed, 0 removed
reading sources... [100%] python
<repo location>/MHKiT/docs/source/ADCP_Delft3D_TRTS_example.ipynb:2181: ERROR: Unexpected indentation.
<repo location>/MHKiT/docs/source/ADCP_Delft3D_TRTS_example.ipynb:2178: WARNING: Inline interpreted text or phrase reference start-string without end-string.
<repo location>/MHKiT/docs/source/ADCP_Delft3D_TRTS_example.ipynb:2182: WARNING: Block quote ends without a blank line; unexpected unindent.
<repo location>/MHKiT/docs/source/ADCP_Delft3D_TRTS_example.ipynb:62: WARNING: image file not readable: data/river/ADCP_transect/TRTS_transect_map.png
<repo location>/MHKiT/docs/source/ADCP_Delft3D_TRTS_example.ipynb:62: WARNING: image file not readable: data/river/ADCP_transect/TRTS_transect_map.png
docstring of mhkit.qc.check_delta:30: WARNING: Definition list ends without a blank line; unexpected unindent.
docstring of mhkit.river.IO.request_usgs_data:20: ERROR: Unexpected indentation.
docstring of mhkit.river.IO.request_usgs_data:21: WARNING: Block quote ends without a blank line; unexpected unindent.
docstring of mhkit.tidal.io.request_noaa_data:17: ERROR: Unexpected indentation.
docstring of mhkit.tidal.io.request_noaa_data:18: WARNING: Block quote ends without a blank line; unexpected unindent.
<repo location>/MHKiT/MHKiT-MATLAB/mhkit/river/performance:docstring of mhkit.river.performance.power_coefficient:1: WARNING: duplicate object description of mhkit.river.performance.power_coefficient, other instance in <repo location>/MHKiT/docs/source/mhkit-matlab/api.river.rst, use :noindex: for one of them
<repo location>/MHKiT/MHKiT-MATLAB/mhkit/river/performance:docstring of mhkit.river.performance.tip_speed_ratio:1: WARNING: duplicate object description of mhkit.river.performance.tip_speed_ratio, other instance in <repo location>/MHKiT/docs/source/mhkit-matlab/api.river.rst, use :noindex: for one of them
<repo location>/MHKiT/MHKiT-MATLAB/mhkit/river/performance:docstring of mhkit.river.performance.circular:1: WARNING: duplicate object description of mhkit.river.performance.circular, other instance in <repo location>/MHKiT/docs/source/mhkit-matlab/api.river.rst, use :noindex: for one of them
<repo location>/MHKiT/MHKiT-MATLAB/mhkit/river/performance:docstring of mhkit.river.performance.rectangular:1: WARNING: duplicate object description of mhkit.river.performance.rectangular, other instance in <repo location>/MHKiT/docs/source/mhkit-matlab/api.river.rst, use :noindex: for one of them
<repo location>/MHKiT/MHKiT-MATLAB/mhkit/river/performance:docstring of mhkit.river.performance.multiple_circular:1: WARNING: duplicate object description of mhkit.river.performance.multiple_circular, other instance in <repo location>/MHKiT/docs/source/mhkit-matlab/api.river.rst, use :noindex: for one of them
<repo location>/MHKiT/MHKiT-MATLAB/mhkit/river/performance:docstring of mhkit.river.performance.ducted:1: WARNING: duplicate object description of mhkit.river.performance.ducted, other instance in <repo location>/MHKiT/docs/source/mhkit-matlab/api.river.rst, use :noindex: for one of them
docstring of mhkit.utils.magnitude_phase:7: WARNING: Definition list ends without a blank line; unexpected unindent.
docstring of mhkit.utils.magnitude_phase:14: ERROR: Unexpected indentation.
docstring of mhkit.wave.IO.hindcast.request_wpto:13: ERROR: Unexpected indentation.
docstring of mhkit.wave.IO.hindcast.request_wpto:15: WARNING: Block quote ends without a blank line; unexpected unindent.
docstring of mhkit.wave.IO.hindcast.request_wpto:28: CRITICAL: Unexpected section title.

Returns
-------
docstring of mhkit.wave.IO.NDBC.NDBC_request_data:17: ERROR: Unexpected indentation.
docstring of mhkit.wave.IO.NDBC.NDBC_request_data:18: WARNING: Block quote ends without a blank line; unexpected unindent.
docstring of mhkit.wave.IO.NDBC.NDBC_available_data:14: ERROR: Unexpected indentation.
docstring of mhkit.wave.IO.NDBC.NDBC_available_data:15: WARNING: Block quote ends without a blank line; unexpected unindent.
docstring of mhkit.wave.graphics.plot_chakrabarti:22: CRITICAL: Unexpected section title or transition.

--------
<repo location>/MHKiT/docs/source/mhkit-python/api.utils.rst:10: WARNING: autosummary: failed to import mhkit.utils.index_to_datetime.
Possible hints:
* AttributeError: module 'mhkit.utils' has no attribute 'index_to_datetime'
* ModuleNotFoundError: No module named 'mhkit.utils.index_to_datetime'
* ImportError:
WARNING: autodoc: failed to import function 'index_to_datetime' from module 'mhkit.utils'; the following exception was raised:
Traceback (most recent call last):
  File "/opt/homebrew/lib/python3.11/site-packages/sphinx/util/inspect.py", line 330, in safe_getattr
    return getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: module 'mhkit.utils' has no attribute 'index_to_datetime'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/opt/homebrew/lib/python3.11/site-packages/sphinx/ext/autodoc/importer.py", line 135, in import_object
    obj = attrgetter(obj, mangled_name)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/sphinx/ext/autodoc/__init__.py", line 319, in get_attr
    return autodoc_attrgetter(self.env.app, obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/sphinx/ext/autodoc/__init__.py", line 2810, in autodoc_attrgetter
    return safe_getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/sphinx/util/inspect.py", line 346, in safe_getattr
    raise AttributeError(name) from exc
AttributeError: index_to_datetime

<repo location>/MHKiT/docs/source/python.rst:32: WARNING: toctree contains reference to nonexisting document 'tidal_performance_example'
<repo location>/MHKiT/docs/source/python.rst:32: WARNING: toctree contains reference to nonexisting document 'mooring_example'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] python
generating indices... genindex mat-modindex py-modindex done
copying linked files...
copying notebooks ... [100%] ADCP_Delft3D_TRTS_example.ipynb
highlighting module code... [100%] pecos.monitoring
writing additional pages... search done
copying images... [100%] figures/mathworks-logo-full-color-rgb.png
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 32 warnings.

The HTML pages are in ..

Build finished. The HTML pages are in .

There are multiple warnings/errors going on. This is a starting point for further investigation

Update MHKiT Termonology

Based on MHKiT-Software/MHKiT-Python#29 and team discussion, a few things need to be done to update the MHKiT Terminology:

add column for Variable definition to MHKiT terminology
add D for "Characteristic Length" to terminology
define lambda_w for "Wave Length" to terminology and update "Wave Number" definition
define "KC" as an acronym to terminology

Live documentation code blocks do not have syntax highlighting

The current live version of the documentation does not have syntax highlighted code blocks.

Live documentation:

On my local machine I built the documentation with:

nbsphinx==0.9.3
sphinxcontrib-matlabdomain==0.21.4
sphinxcontrib-bibtex==2.6.2
sphinx-rtd-theme==2.0.0

Which was installed with pip install -U sphinxcontrib-bibtex sphinxcontrib-matlabdomain sphinx_rtd_theme nbsphinx per the README. Notably, these versions differ from the listed versions. Some package amongst these includes code block syntax highlighting.

Long term this can be solved by a more consistent Build/CI step. In the short term does it make sense to use the latest versions of the above packages? The docs build properly (at least for me), and the addition of syntax highlighting contributes to an improved user experience.

Add conda install to Docs

MHKiT-Python can now be install via conda-forge:

MHKiT-Software/MHKiT-Python#274

Images Not showing Up in Examples

@rpauly18 pointed this out this morning and I have confirmed

General documentation updates

Priorities before OREC:

Update all links #60
Ensure installation instructions are very clear for both Python and MATLAB #58
Ensure compatible Python versions (3.8-3.11) and dependencies are clear #60

Improving our API documentation

We can further reduce duplication of text in our API by replacing all high level descriptions of modules with the automodule feature. Modules have varying level of detail and should be kept up to date in the source, which is then propagated to the API.

e.g. the mhkit-python/api.mooring.rst was previously the following::

IO
""""""""""""
The io submodule contains a function to
load MoorDyn data and convert it to xarray:

.. autosummary::
   :nosignatures:
   
   ~mhkit.mooring.io.read_moordyn

.. automodule:: mhkit.mooring.io
    :members:
    :undoc-members:
    :show-inheritance:

Instead we can replace the short sentence with the automodule which is more detailed.

Also, it is unclear to me when we would use autosummary vs autofunction in the API. Our use seems inconsistent.

mhkit-software / mhkit Goto Github PK

mhkit's People

Stargazers

Watchers

Forkers

mhkit's Issues

Recommend Projects

Recommend Topics

Recommend Org