astropy / astropy/sphinx-automodapi
"duplicate object description" warning for classes/functions defined in __init__.py.
- 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