Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Duplication #527

Open
eloitanguy opened this issue Sep 21, 2023 · 0 comments
Open

Documentation Duplication #527

eloitanguy opened this issue Sep 21, 2023 · 0 comments

Comments

@eloitanguy
Copy link
Collaborator

eloitanguy commented Sep 21, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant