[JOSS] improving docs by using intersphinx?

[sappelhoff]

(related to https://github.com/openjournals/joss-reviews/issues/3293)

I noticed that several times throughout the docs you refer to methods, classes, etc. of other Python packages, such as Pandas.DataFrame.

Through the intersphinx sphinx extension, it is possible to have sphinx automatically render these references as links to those documentations. So that Pandas.DataFrame would lead to the pandas docs on DataFrame.

You can have a look of this in action here: https://mne.tools/mne-bids/stable/generated/mne_bids.write_raw_bids.html#mne_bids.write_raw_bids

This also extends to the API docs, so that parameter data types are also linked to what they are. That's particularly useful in cases like the following:

your own functions like fitgrid.load_grid sometimes have parameters like so:

grid – loaded FitGrid object

With intersphinx, "FitGrid object" can become a link that leads users to the docs of FitGrid object, without having to search for it.

---

Overall using this feature will require some minimal syntactical changes in the docs and docstrings here and there, and some additions to docs/conf.py --> but I am pretty sure it'll be well worth it.

[sappelhoff]

Thanks for adding these. I see some links working now, some others do not work (yet).

What doesn't work:

• see: https://kutaslab.github.io/fitgrid-dev-docs/quick_reference.html#model-running
• for example the RHS (str) parameter --> the str should be a link to the Python docs, like for example int in these docs: https://pyprep.readthedocs.io/en/latest/generated/pyprep.NoisyChannels.html#pyprep.NoisyChannels
• there are other cases like that, but I don't know why it doesn't work right now.

What works:

• the "return type" fields in the API docs
• several other links in the gallery examples

[turbach]

@sappelhoff yes, I see where the pyprep and the MNE Python docs link parameters back to the Python docs. On the other hand, the numpy, pandas, or matplotlib docs don't do this: numpy.ndarray, pandas.DataFrame, matplotlib.figure.Figure

I believe the fitgrid docs can be built either way via the napoleon_use_param boolean in the sphinx conf.py and it is currently set to False in line with numpy, pandas, and matplotlib.

So my take is everything works as intended, the issue is about the docs style. I don't have a strong opinion ... don't see what harm the links do (so why not?) or what use they are in practice (so why?).

@andportnoy any thoughts?

[sappelhoff]

So my take is everything works as intended, the issue is about the docs style. I don't have a strong opinion ... don't see what harm the links do (so why not?) or what use they are in practice (so why?).

I see, thanks for looking into this! I'll check this off on my JOSS list then, and you can feel free to close it once you either decide to (1) keep it how it is, or (2) implement it differently.