readthedocs / readthedocs/sphinx-autoapi

Add header before module contents docs when showing summaries

Open
#351 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
494
Forks
147
Avg merge
9m
Merged PRs (30d)
1

Description

Currently, if you include the option show-module-summary, then for themes with contents sidebars (such as jupyter-book), then the lack of a new header before the full module contents docs (i.e. after the last module summary section) means that the page's hierarchy is mis-represented.

For example, take the following module, containing a class, attribute and function:

Screenshot 2022-09-21 at 22 31 45

Here we can see the right-hand sidebar displays the contents as one would expect, with each docs entry being a new section in the contents.

However, if we turn on module summaries, we get the following:

Screenshot 2022-09-21 at 22 31 17

Here we can see that the docs entries are displayed as being contents within the last of the module summary sections (in this case Attributes, rather than being listed either as at the same hierarchy as the summary sections, or within a new section, thereby indicating they're not within Attributes.

I'm not sure what the preferred fix for this would be, but probably the most consistent thing would be to move the summary sections into a section above Module Contents, such as Module Summary, and then have the contents be subsections of Module Contents (as it they are in the non-summary case).

For example, in the above example the new section header structure would be as follows:

# Module Summary
## Classes
## Functions
## Attributes
# Module Contents
## Foo
## bar
## baz

Contributor guide

No contributing guide indexed for this repository

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

Start by locating the handling for the show-module-summary option and the code that generates module contents headings, then compare its output with and without summaries. Done means the generated hierarchy separates the summary sections from a new Module Contents section while preserving the expected contents sidebar structure.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.