sphinx-doc / sphinx-doc/sphinx
Autosummary : Modules with the package's name may hide documentation pages links
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
If we have a module that has the package's name (For example, mytoolbox.py within mytoolbox). Then, it seems that imported modules inside mytoolbox.py are hidden, their documentation is correctly generated but no links are embedded to these documentation pages.
Consider the following package:
── mytoolbox
├── init.py
├── mytoolbox.py
├── mymodule1.py
├── mymodule2.py
└── mysubpackage
If we have from mytoolbox import mymodule1 in mytoolbox.py, the documentation for mytoolbox.mymodule1 is correctly generated (mytoolbox.mymodule1.html) but there are no links to this page in the API Reference page (ie mytoolbox.html).
How to Reproduce
$ git clone https://github.com/MAJegham/Sphinx-Autosummary-Recursion.git
$ cd Sphinx-Autosummary-Recursion
$ pip install -r requirements.txt
$ cd docs
$ make html
open _build/html/_autosummary/mytoolbox.html and see a functioning link to mytoolbox.mymodule1 page
Expected behavior
have a functioning link to mytoolbox.mymodule's doc in the page _build/html/_autosummary/mytoolbox.html
Your project
https://github.com/MAJegham/Sphinx-Autosummary-Recursion
Screenshots

mytoolbox.mymodule1 (in pink) is not a link even though the page mytoolbox/mymodule1.html was correctly generated.
OS
ubuntu 20.04
Python version
3.8.10
Sphinx version
5.0.2
Sphinx extensions
autosummary, autodoc
Extra tools
No response
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the case in the linked Sphinx-Autosummary-Recursion project by running pip install -r requirements.txt, cd docs, and make html. Compare the generated _build/html/_autosummary/mytoolbox.html with mytoolbox.mymodule1.html and trace the autosummary/autodoc entry points; done means the API Reference page contains a working link to the generated module documentation.
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