Allow me to add a GLORIOUS _{(but not perfect)} solution to your list.

The Problem

If you put an imported attribute without the full prefix within .. autosummary:: or after .. autodata::, Sphinx will insert the docstring of the attribute's type.

For example, if you write something like:

.. automodule:: rogue_scroll

   .. autosummary::

      SYLLABLES

.. autodata:: SYLLABLES

You would get something like:

It is not easy to automatically (not hardcode) get the full path of an imported attribute. Even inside a template, you do not have easy access to that information. But I am here to the rescue!

The Solution

It is a three-step solution:

Generate an attribute list (including full module prefix) for each module using sphinx-autogen and template magic.
Use some GNU Make functions to generate a combined list of all attributes.
Use the combined attribute list within the template to generate the final module documentation.

sphinx-autogen is a command-line tool shipped with Sphinx. It is also used automatically under the hood by the directive .. autosummary:: with the option :toctree:.

I am using Python 3.13 and Sphinx 8.2.3.

Project structure

├─ src/
│  └─ rogue_scroll/
│     ├─ __init__.py
│     └─ _scroll.py
└─ docs/
   ├─ Makefile
   ├─ *build/
   └─ source/
      ├─ conf.py
      ├─ index.rst
      ├─ modules.rst
      ├─ autogen_attributes.rst
      ├─ *_attributes/
      ├─ *_autosummary/
      ├─ _static/
      └─ _templates/
         └─ autosummary/
            ├─ attributes.rst
            └─ module.rst

*Generated during build

The attribute lists will be placed in the directory docs/source/_attributes/. The final documentation will be generated in docs/build/. Open the file docs/build/html/index.html to visualize it.

docs/Makefile

SOURCE_DIR        := source
BUILD_DIR         := build
TEMPLATES_DIR     := $(SOURCE_DIR)/_templates
AUTOSUMMARY_DIR   := $(SOURCE_DIR)/_autosummary
ATTRIBUTES_DIR    := $(SOURCE_DIR)/_attributes
ATTRIBUTES_LIST   := $(ATTRIBUTES_DIR)/list.rst
AUTOGEN_ATTR_FILE := $(SOURCE_DIR)/autogen_attributes.rst

.PHONY: html attributes
html: $(ATTRIBUTES_LIST)
    sphinx-build -M html $(SOURCE_DIR) $(BUILD_DIR) -v -a -E

$(ATTRIBUTES_LIST): attributes
    $(file > $(ATTRIBUTES_LIST),$(subst $(eval ) ,,\
        $(foreach FILE,$(wildcard $(ATTRIBUTES_DIR)/*),\
        $(firstword $(file < $(FILE))))))

attributes: $(AUTOGEN_ATTR_FILE)
    rm -rf $(ATTRIBUTES_LIST)
    export PYTHONPATH=../src && sphinx-autogen -i -t $(TEMPLATES_DIR) $<

When you execute make html to build the documentation, the Makefile will execute the following commands:

rm -rf source/_attributes/list.rst
export PYTHONPATH=../src && sphinx-autogen -i -t source/_templates source/autogen_attributes.rst
sphinx-build -M html source build -v -a -E

docs/source/conf.py

import os
import sys

sys.path.insert(0, os.path.abspath('../../src'))

project = "Project name"
author = "Author name"
version = "1.0.0"
release = version
copyright = f"2025, {author}"

extensions = ['sphinx.ext.autodoc','sphinx.ext.autosummary']
templates_path = ['_templates']
exclude_patterns = ['build', '_attributes', 'autogen_attributes.rst']
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
autosummary_imported_members = True

Note that autogen_attributes.rst and _attributes/ are listed in exclude_patterns, because they are only used to generate the attributes list and must not be included in the final documentation.

Also, I am using the "Read The Docs" theme because it is pretty :). You can install it executing pip install sphinx-rtd-theme.

docs/source/index.rst

Main page title
===============

.. toctree::
   :maxdepth: 3

   modules

Main file of the documentation.

docs/source/modules.rst

Modules
=======

.. autosummary::
   :toctree: _autosummary
   :template: module
   :recursive:

   rogue_scroll

This file generates documentation for each module using the template docs/source/_templates/module.rst. The reST files generated during build will be placed in docs/source/_autosummary.

docs/source/autogen_attributes.rst

.. autosummary::
   :toctree: _attributes
   :template: attributes
   :recursive:

   rogue_scroll
   rogue_scroll._scroll

This is the main file parsed by sphinx-autogen to generate an attribute list for each module using the template docs/source/_templates/attributes.rst. Usually, you would include only the top-level package (rogue_scroll), but Sphinx does not include private modules (any file starting with _) by default, so I had to include rogue_scroll._scroll manually.

docs/source/_templates/attributes.rst

{# PART 1 --------------------------------------------------------------------#}

{% for a in attributes -%}
   {{ '%s.%s,' % (fullname, a) -}}
{% endfor -%}

{# PART 2 --------------------------------------------------------------------#}

{{ ',\n\n.. automodule:: %s\n\n' % fullname -}}

{% if modules -%}
   {{ '   .. autosummary::\n'
      '      :toctree:\n'
      '      :template: attributes\n'
      '      :recursive:\n\n' -}}
   {% for m in modules -%}
      {{ '      %s\n' % m -}}
   {% endfor -%}
{% endif -%}

This template is used to generate an attribute list for each module.

PART 1: This part generates a comma separated list of the module attributes.
PART 2: This part is necessary to search all the modules in the package recursively. This part will be stripped by the GNU Make functions when generating the combined list.

docs/source/_templates/module.rst

{{ fullname | underline }}

{# PART 1 --------------------------------------------------------------------#}

{% set attributes_file -%}
   {% include '../_attributes/list.rst' -%}
{% endset -%}

{% set global_attributes = attributes_file.split(',') -%}

{% for a in global_attributes -%}
   {% if a == '' -%}
      {% set _ = global_attributes.pop(loop.index0) -%}
   {% endif -%}
{% endfor -%}

{# PART 2 --------------------------------------------------------------------#}

{% set imported_attributes = [] -%}

{% for m in members -%}
   {% if m not in modules ~ functions ~ classes ~ exceptions ~ attributes -%}
      {% set outer_loop = loop -%}
      {% for a in global_attributes -%}
         {% if m == a.split('.')[-1] -%}
            {% set _ = imported_attributes.append((a, m)) -%}
         {% endif -%}
      {% endfor -%}
   {% endif -%}
{% endfor -%}

{# PART 3 --------------------------------------------------------------------#}

{{ '.. automodule:: %s' % fullname -}}

{% if attributes or imported_attributes -%}
   {{ '\n\n   .. autosummary::\n\n' -}}
   {% for a in attributes -%}
      {{ '      ~%s\n' % a -}}
   {% endfor -%}
   {% if imported_attributes -%}
      {% for a in imported_attributes -%}
         {{ '      ~%s\n' % (a[0].replace('%s.' % fullname, '', 1)) -}}
      {% endfor -%}
   {% endif -%}
{% endif -%}

{# PART 4 --------------------------------------------------------------------#}

{% if attributes or imported_attributes -%}
   {% for a in attributes if a in members -%}
      {{ '\n.. autodata:: %s\n' % a -}}
   {% endfor -%}
   {% if imported_attributes -%}
      {% for a in imported_attributes -%}
         {{ '\n.. py:data:: %s\n\n' % a[1] -}}
         {{ '   .. autodata:: %s\n' % a[0] -}}
         {{ '      :noindex:\n' -}}
      {% endfor -%}
   {% endif -%}
{% endif -%}

{# PART 5 --------------------------------------------------------------------#}

{{ '\n\nname: %s\n\n' % name -}}
{{ 'objname: %s\n\n' % objname -}}
{{ 'fullname: %s\n\n' % fullname -}}
{{ 'objtype: %s\n\n' % objtype -}}
{{ 'module: %s\n\n' % module -}}
{{ 'class: %s\n\n' % class -}}
{{ 'members: %s\n\n' % members -}}
{{ 'inherited_members: %s\n\n' % inherited_members -}}
{{ 'functions: %s\n\n' % functions -}}
{{ 'classes: %s\n\n' % classes -}}
{{ 'exceptions: %s\n\n' % exceptions -}}
{{ 'methods: %s\n\n' % methods -}}
{{ 'attributes: %s\n\n' % attributes -}}
{{ 'modules: %s\n\n' % modules -}}

{{ 'global_attributes:\n' -}}
{% for a in global_attributes -%}
   {{ '   %s,\n' % a -}}
{% endfor -%}
{{ '\n' -}}

{{ 'imported_attributes:\n' -}}
{% for a in imported_attributes -%}
   {{ '   (%s, %s),\n' % a -}}
{% endfor -%}
{{ '\n' -}}

This template is used to generate the documentation for each module.

PART 1: Read the combined attribute list file and create a list variable global_attributes.
PART 2: Check which attributes from global_attributes were imported and create the imported_attributes list.
PART 3: Generate a summary of the attributes.
PART 4: That is a tricky part. I want to document the imported attribute at the top-level package, to show the user that the constant rogue_scroll.SYLLABLES is available. However, I cannot use directive .. autodata::, as mentioned in the problem section. So I decided to use .. py:data:: for the top-level attribute and, inside it, .. autodata:: for the full path attribute to get the correct docstring.
PART 5: This part is optional for debug purposes. It will print all the variables available to use inside the template.

src/init.py

"""rogue_scroll docstring"""

from ._scroll import SYLLABLES
from ._scroll import SCROLL_PROBS

src/_scroll.py

"""_scroll docstring"""

SYLLABLES = 123
"""SYLLABLES docstring"""

SCROLL_PROBS = 123
"""SCROLL_PROBS docstring"""

The Result

I created this answer specifically for your case (Merry Christmas!), but I posted a more complete and generic example on my GitHub. It is licensed under the "do whatever the f*** you want" license (MIT).

This solution is not absolute. It is just a result of many days of research and template tinkering. 100% AI-free. If you can improve this solution somehow, please let me know!

For more details about templates, see [1] and [2].

79788781