You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 autosummaryand through the automodule (as ot.unif), and thus documents it twice in the ot.utilsdocumentation. 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.
The text was updated successfully, but these errors were encountered:
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 forSphinx
to find docstrings:ot
modules,ot.something
, to my understanding.Now in order to have nice access to ot functions such as
ot.unif
orot.emd
, they are imported in the init file.My theory is that
Sphinx
findsot.utils.unif
through theautosummary
and through theautomodule
(asot.unif
), and thus documents it twice in theot.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
withot.unif
, and yields a double documentation oftic, 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
andot.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 likeot.unif
, which would not be acceptable.The text was updated successfully, but these errors were encountered: