search

MHKiT-Software / MHKiT

MHKiT Documentation
https://MHKiT-Software.github.io/MHKiT/
4 stars 14 forks source link

Resolved MHKiT-MATLAB API Documentation Issues #16

Closed kmruehl closed 4 years ago

kmruehl commented 4 years ago

This PR resolves the issues with the MHKiT-MATLAB API Documentation. Both the MATLAB and Python API documentation are now generated within the MHKiT repositories. They generate documentation using the MHKiT-MATLAB and MHKiT-Python GitHub submodules.

@rpauly18 this means you should remove the \docs directory from the MHKiT-MATLAB repository. However, we will still need to save the MATLAB live examples as html files in the \examples directory.

I have an example of what this new documentation looks like on my fork here: https://kmruehl.github.io/MHKiT/.

kmruehl commented 4 years ago

A couple of minor comments to clean up. In today's meeting, I would like to discuss our documentation binary strategy here as there seems to be a lot.

Sounds good. The only way I'm aware of removing binaries from the repository is to configure Travis CI or ReadTheDocs to compile the documentation.

kaklise commented 4 years ago

I didn’t add anything to autogenerate documentation on the Matlab side.

@kmruehl commented on this pull request.

In docs/_sources/mhkit-matlab/api.river.rst.txthttps://github.com/MHKiT-Software/MHKiT/pull/16#discussion_r416119567:

@kaklisehttps://github.com/kaklise this code appears in each of the modules, and was originally in the MHKiT-Python API. I think the intent was to autodoc on the module level, (e.g. device, graphics, io, resource) but it doesn't appear to generate anything. Is this necessary for the API doc? —

kmruehl commented 4 years ago

@kaklise My apologies, I thought this autdoc code was on the API for both MHKiT-MATLAB and MHKiT-Python, but you're right, it was just on the MHKiT-MATLAB side. The code has been removed.

kmruehl commented 4 years ago

A couple of minor comments to clean up. In today's meeting, I would like to discuss our documentation binary strategy here as there seems to be a lot.

Sounds good. The only way I'm aware of removing binaries from the repository is to configure Travis CI or ReadTheDocs to compile the documentation.

@ssolson all of your requested revisions are on my https://github.com/kmruehl/MHKiT-1 fork. @rpauly18 did you have any requests?

rpauly18 commented 4 years ago

@kmruehl No, requests. all your changes look good. Some of the code that did nothing were left over from when I was initially trying to get this to work, so there should be no issues with removing it.

kmruehl commented 4 years ago

@kmruehl No, requests. all your changes look good. Some of the code that did nothing were left over from when I was initially trying to get this to work, so there should be no issues with removing it.

Thanks @rpauly18. That's helpful background. It looks like the automodule API documentation works for functions within a submodule (e.g. mhkit.wave.io.read_NDBC_file), but not for submodules within a module (e.g. wave.io, wave.resource, wave.performance, wave.graphics). There may be another way to generate submodule API documentation. We can look into this in the future.

@ssolson @rpauly18 can one of you merge this PR? There are no conflicts with master.

ssolson commented 4 years ago

Thanks Kelly. Let me pull the latest and test it. I'll merge if no issues arise.