POT
POT copied to clipboard
Documentation Duplication
Describe the bug
Many functions have duplicated documentation
To Reproduce
Steps to reproduce the behavior:
Go to the documentation of ot.utils
, ot.utils.unif
is documented twice.
Note that when building the documentation for the first time, a Warning is raised for this:
ot/utils.py:docstring of ot.utils.unif:1: WARNING: duplicate object description of ot.utils.unif, other instance in gen_modules/ot.utils, use :no-index: for one of them
Ideas
In docs/source/all.rst
, there are two indicators for Sphinx
to find docstrings:
- The autosummary, which allows it to find the different
ot
modules, - The automodule, which instructs it to find any
ot.something
, to my understanding.
Now in order to have nice access to ot functions such as ot.unif
or ot.emd
, they are imported in the init file.
My theory is that Sphinx
finds ot.utils.unif
through the autosummary
and through the automodule
(as ot.unif
), and thus documents it twice in the ot.utils
documentation. This theory is supported by the fact that most (all?) of the functions imported likewise in the __init__.py
file are documented twice. Finally, the order seems to corroberate this idea: in __init__.py
, the line:
from .utils import dist, unif, tic, toc, toq
is the last interaction of Sphinx
with ot.unif
, and yields a double documentation of tic, toc, toq, unif
at the end of the page. (dist
is also duplicated, but placed differently for some reason).
This duplication is annoying, because we do want to document both ot.unif
and ot.utils.unif
(for example), and the current method is an easy automatic way of doing it. I'm sorry to say I have no idea how to solve this duplication without removing the documentation for shortcuts like ot.unif
, which would not be acceptable.