astropy / astropy/sphinx-automodapi

Non predictable permalinks when multiple automodapi directive is used

Open
#145 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
Python
Stars
67
Forks
48
Avg merge
11h 52m
Merged PRs (30d)
1

Description

Identified as an issue in https://github.com/astropy/pyvo/pull/289#issuecomment-1048753250

E.g. here the first one gets the `classes` and `functions` link, but the rest just a numbered ID, which is then not very informative to be used elsewhere as a reference, as well as non-future proof, basically making these headings useless to be cross-linked.

Example from the astropy core docs:
docs/modeling/reference_api.rst
https://docs.astropy.org/en/stable/modeling/reference_api.html

One solution could be that the module names are inherited into those heading links, e.g.
https://docs.astropy.org/en/stable/modeling/reference_api.html#functions becomes https://docs.astropy.org/en/stable/modeling/reference_api.html#module-astropy.modeling.functions

While https://docs.astropy.org/en/stable/modeling/reference_api.html#id9 becomes https://docs.astropy.org/en/stable/modeling/reference_api.html#module-astropy.modeling.statistic.functions

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with docs/modeling/reference_api.rst and reproduce the multiple automodapi directives shown in the issue, comparing the generated anchors with the linked Astropy documentation. Done means repeated sections receive stable, informative module-based links instead of numbered IDs that cannot be reliably cross-linked.

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
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.