astropy / astropy/sphinx-automodapi

"duplicate object description" warning for classes/functions defined in __init__.py.

Open
#54 0 comments 6 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
67
Forks
48
Avg merge
11h 52m
Merged PRs (30d)
1

Description

Hello,

I have an [\_\_init\_\_.py](https://gitlab.com/picos-api/picos/blob/future+paths/picos/solvers/__init__.py) file that defines an exception and a number of functions. I want to document it as follows (from `/…/src/picos/doc/api/solvers.rst`):
```
.. automodapi:: picos.solvers
:no-heading:
:headings: =-
```
The documentation generates fine, but I get the following warnings
```
/…/src/picos/picos/solvers/__init__.py:docstring of picos.solvers.NoAppropriateSolverError:1: WARNING: duplicate object description of picos.solvers.NoAppropriateSolverError, other instance in /…/src/picos/doc/api/solvers.rst, use :noindex: for one of them
/…/src/picos/picos/solvers/__init__.py:docstring of picos.solvers.all_solvers:1: WARNING: duplicate object description of picos.solvers.all_solvers, other instance in /…/src/picos/doc/api/solvers.rst, use :noindex: for one of them
/…/src/picos/picos/solvers/__init__.py:docstring of picos.solvers.available_solvers:1: WARNING: duplicate object description of picos.solvers.available_solvers, other instance in /…/src/picos/doc/api/solvers.rst, use :noindex: for one of them
/…/src/picos/picos/solvers/__init__.py:docstring of picos.solvers.get_solver:1: WARNING: duplicate object description of picos.solvers.get_solver, other instance in /…/src/picos/doc/api/solvers.rst, use :noindex: for one of them
/…/src/picos/picos/solvers/__init__.py:docstring of picos.solvers.potential_solvers:1: WARNING: duplicate object description of picos.solvers.potential_solvers, other instance in /…/src/picos/doc/api/solvers.rst, use :noindex: for one of them
/…/src/picos/picos/solvers/__init__.py:docstring of picos.solvers.suggested_solver:1: WARNING: duplicate object description of picos.solvers.suggested_solver, other instance in /…/src/picos/doc/api/solvers.rst, use :noindex: for one of them
```
I verified that these are the only definitions of the exception and the functions in question.

I don't know how to get rid of the warnings and I suspect that this is an issue with `automodapi`.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the automodapi directive in doc/api/solvers.rst and the definitions and docstrings in picos/solvers/__init__.py. Reproduce the Sphinx build and trace how automodapi handles objects defined in __init__.py; done means the documented exception and functions no longer produce duplicate object description warnings.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.