Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

autosummary does not render docstrings if multiple docstrings have the same link text #13311

Open
kratsg opened this issue Feb 7, 2025 · 0 comments
Labels

Comments

@kratsg
Copy link

kratsg commented Feb 7, 2025

Describe the bug

If multiple docstrings are being rendered using sphinx.ext.autosummary and they have the same custom link text, the duplicate ones will not get rendered on the page.

How to Reproduce

conf.py

from __future__ import annotations

import importlib.metadata
from typing import Any

from intersphinx_registry import get_intersphinx_mapping

project = "atlas-schema"
copyright = "2024, Giordon Stark"
author = "Giordon Stark"
version = release = importlib.metadata.version("atlas-schema")

extensions = [
    "myst_parser",
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.coverage",
    "sphinx.ext.githubpages",
    "sphinx.ext.ifconfig",
    "sphinx.ext.intersphinx",
    "sphinx.ext.mathjax",
    "sphinx.ext.napoleon",
    "sphinx.ext.viewcode",
    "sphinx_autodoc_typehints",
    "sphinx_copybutton",
    "sphinx_click.ext",
    "sphinx_issues",
]

# GitHub repo
issues_github_path = "scipp-atlas/atlas-schema"

# Generate the API documentation when building
autosummary_generate = True
numpydoc_show_class_members = False

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
source_suffix = [".rst", ".md"]
exclude_patterns = [
    "_build",
    "**.ipynb_checkpoints",
    "Thumbs.db",
    ".DS_Store",
    ".env",
    ".venv",
]

html_theme = "furo"

html_theme_options: dict[str, Any] = {
    "footer_icons": [
        {
            "name": "GitHub",
            "url": "https://github.com/scipp-atlas/atlas-schema",
            "html": """
                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
                </svg>
            """,
            "class": "",
        },
    ],
    "source_repository": "https://github.com/scipp-atlas/atlas-schema",
    "source_branch": "main",
    "source_directory": "docs/",
}

myst_enable_extensions = [
    "colon_fence",
]

intersphinx_mapping = get_intersphinx_mapping(
    packages={
        "python",
    }
)

nitpick_ignore = [
    ("py:class", "_io.StringIO"),
    ("py:class", "_io.BytesIO"),
]

always_document_param_types = True

# sphinx-copybutton configuration
copybutton_prompt_text = r">>> |\.\.\. |\$ "
copybutton_prompt_is_regexp = True
copybutton_here_doc_delimiter = "EOF"

index.md

# atlas-schema

```{toctree}
:maxdepth: 2
:hidden:
api
```

```{include} ../README.md
:start-after: <!-- SPHINX-START -->
```

## Indices and tables

- {ref}`genindex`
- {ref}`modindex`
- {ref}`search`

api.rst

Python API
==========

Enums
-----

.. currentmodule:: atlas_schema.enums

.. autosummary::
   :toctree: _generated/
   :nosignatures:

   ParticleType
   ParticleOrigin
   PhotonID

src/atlas_schema/enums.py (part 1)

from __future__ import annotations

from enum import IntEnum


class ParticleType(IntEnum):
    """
    Docstring1 `Take <https://google.com>`_.
    """


class ParticleOrigin(IntEnum):
    """
    Docstring2 `Take2 <https://github.com>`_.
    """


class PhotonID(IntEnum):
    """
    Docstring3 `Take2 <https://google.com>`_.
    """
Image

src/atlas_schema/enums.py (part 2)

from __future__ import annotations

from enum import IntEnum


class ParticleType(IntEnum):
    """
    Docstring1 `Take <https://google.com>`_.
    """


class ParticleOrigin(IntEnum):
    """
    Docstring2 `Take <https://github.com>`_.
    """


class PhotonID(IntEnum):
    """
    Docstring3 `Take2 <https://google.com>`_.
    """
Image

Environment Information

Platform:              darwin; (macOS-14.6.1-arm64-arm-64bit)
Python version:        3.11.9 (main, Oct 17 2024, 11:28:11) [Clang 16.0.0 (clang-1600.0.26.3)])
Python implementation: CPython
Sphinx version:        8.1.3
Docutils version:      0.21.2
Jinja2 version:        3.1.5
Pygments version:      2.19.1

Sphinx extensions

`["sphinx.ext.autodoc", "sphinx.ext.autosummary"]`

Additional context

No response

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

1 participant