search

SNL-WaterPower / WecOptTool-MATLAB

WEC Design Optimization Toolbox
GNU General Public License v3.0
12 stars 9 forks source link

Sphinx Docs Deployment Pitfalls #100

Closed H0R5E closed 4 years ago

H0R5E commented 4 years ago

@H0R5E wrote:

So the plan is to store the sphinx source on master and push the build to gh-pages. You can follow #82 for the implementation until its merged. The next step is to automatically build the docs on a master branch merge. See #72 and #81.

@kmruehl wrote:

I'll take a look at #82 . This is an issue we are currently trying to resolve with MHKiT-MATLAB. Right now we are compiling them in master and copying them over to gh-pages, which is a short-term solution, and has obvious drawbacks... including that we lose the index.

@kmruehl, continuing on from #65, I wonder if you would mind giving me more details about what problems you are having with this approach (which seems like a facsimile of ours)? I notice you are trying to merge your docs into another set of docs (is this where you lose your index?). What are the other problems you are having?

kmruehl commented 4 years ago

@H0R5E sorry for the slow reply. Looping in @ssolson since he works on both codes, and @rpauly18 since she's leading MHKiT-MATLAB development.

MHKiT is written in both MATLAB and Python. The MHKiT documentation is hosted here, and the MHKiT-Python and MHKiT-MATLAB source code are hosted on two separate repositories.

We have no issues compiling the MHKiT-Python API documentation. We have a set relative path to clone each repository, and point to the python source code to generate the API documentation. Refer to: https://mhkit-software.github.io/MHKiT/python.html# and https://mhkit-software.github.io/MHKiT/python.html#api-documentation.

However, the only way we could get the MHKiT-MATLAB API documentation to work is by running sphinx locally to compile documentation in the MHKiT-MATLAB repository, and then copy the generated HTML files into the MHKiT documentation repository, and push it online. This creates two issues:

  1. The workflow is not straightforward
  2. The index gets removed when you navigate from https://mhkit-software.github.io/MHKiT/matlab.html to https://mhkit-software.github.io/MHKiT/source/mhkit-matlab/mhkit.wave.html

@rpauly18 feel free to clarify and/or create issue on https://github.com/MHKiT-Software/MHKiT/issues

kmruehl commented 4 years ago

@H0R5E I was able to resolve the API doc issue by pulling MHKiT-MATLAB and MHKiT-Python repositories into the MHKiT documentation repo as submodules. I then specified the MATLAB source path in the conf.py file, and differentiated between MATLAB and Python source using the .. mat:automodule:: flag described here: https://pypi.org/project/sphinxcontrib-matlabdomain/.