ReadTheDocs compile warnings

[handwerkerd]

Summary

When I tried to compile the documentation with "make html" I saw a bunch of warnings. Some were minor, but many seem to be because files or functions were moved into different subdirectories from when api.rst was first made. I think this means that not all functions will automatically have documentation rendered.

Additional Detail

Some warnings include:
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:11: WARNING: toctree references unknown document 'generated/tedana.workflows'
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:30: WARNING: toctree references unknown document 'generated/tedana.decay'
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:49: WARNING: toctree references unknown document 'generated/tedana.combine'
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:67: WARNING: toctree references unknown document 'generated/tedana.decomposition'
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:90: WARNING: toctree references unknown document 'generated/tedana.metrics'
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:113: WARNING: toctree references unknown document 'generated/tedana.selection'
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:136: WARNING: toctree references unknown document 'generated/tedana.gscontrol'
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:155: WARNING: toctree references unknown document 'generated/tedana.io'
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:181: WARNING: toctree references unknown document 'generated/tedana.stats'
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:201: WARNING: toctree references unknown document 'generated/tedana.utils'

There's also a repeated warning:
/Users/handwerkerd/code/tedana_community/handwerkerd/tedana/docs/api.rst:39: WARNING: Duplicate explicit target name: "calibration_ref".
because .. _calibration_ref: is repeated throughout api.rst rather than being changed for each section.

Next Steps

I started to fix a couple of these, but it would go faster if someone who moved some of these function files around & know what was initially intended for each section can correct this.

[emdupre]

This discussion has mostly taken place on gitter, with @jbteves and @handwerkerd. Forcing the api.rst to re-generate solved the majority of these issues, as functions had been renamed and moved since it's creation !

[emdupre]

Moving over from gitter :

Joshua Teves @jbteves 15:40
So if you run make html it only makes the html pages, wouldn’t we need to run some other make? The api.rst file doesn’t get made when I run that.
And for clarity, you mean that it builds everything on the RTD site except the API page?

I was muddled on this myself, but I sat down and looked through -- my current thinking is this (and I'll update a PR to patch these issues):

• The generated folder is out of date. We should remove it and then add it to our .gitignore.
• Most of the remaining errors in api.rst are because we did significant refactoring without updating the documentation references. We should keep api.rst committed, and it will automagically populate it with docstrings, but we need the correct functions in-place.

[tsalo]

docs/generated is already in the gitignore.

I believe most of the warnings come from how autosummary and automodule are set up. Automodule automatically puts the docstrings on a single page, which is ugly. Autosummary requires that we include the functions/classes/modules we want documented explicitly, and it also renders modules on their own pages. This is suboptimal because it means that we don't have files for a lot of the API by default, and the modules that we do document end up having duplicates of the entries we placed in the autosummary list.

Things would be easier if we could figure out how to make it so every function, class, and module has its own html page, which would eliminate duplicate entries (e.g., when we manually put a function in api.rst and include auto summary for the module as well) and would mean that the files would exist that the toctree expects. I haven't figured out how to do that though.

A number of warnings are also because the functions template looks for the examples section (or maybe actual examples that reference the function?) even though none of our current functions have them.

[emdupre]

OK, this was a combination of several problems.. @rmarkello took a look at it and updated to patch the errors. Ended up incorporating this into #340 -- hope that's alright ! The good news is, building locally with these changes we're seeing zero warnings (as long as you have LaTeX installed on your local machine).

A number of warnings are also because the functions template looks for the examples section (or maybe actual examples that reference the function?) even though none of our current functions have them.

Since we're not actually using Sphinx Gallery, we've commented this line out for now. Once we have examples, it'd be grea to uncomment and have those displayed !

[emdupre]

Closed with #340.