sphinx-doc / sphinx-doc/sphinx

Autosummary : Modules with the package's name may hide documentation pages links

Open
#10,587 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autosummary type:bug
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

image

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.