sphinx-doc / sphinx-doc/sphinx

Auto-pluralize glossary terms (via flag, maybe)

Open
#7,574 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

domains:std type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.

When referring to glossary items, you have to follow the exact form, and have to specify singular and plural form separately:

.. glossary::

   foo
      Text.

This works: One :term:`foo`.

This does not work: Many :term:`foos`.

Workaround #1: Many :term:`foos <foo>`. But it's annoyingly verbose.

Workaround #2: Many :term:`foo`\s. But it's kinda ugly and rendered output is ugly too.

.. glossary::

   workaround
   workarounds
      Text.

Workaround #3: Many :term:`workarounds`. But then glossary looks awful.

.. |foos| replace:: :term:`foos <foo>`

Workaround #4: Many |foos|. But the syntax is completely different, you lose static validation (depends on editor) and so on.

Describe the solution you'd like

How about simply auto-building the plural form for glossary targets? Adding s would work for English (for most cases) but probably not for other languages, so it should be configurable.

Describe alternatives you've considered

No idea.

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

The issue names no implementation files, tests, or entry points. Start by clarifying the configurable pluralization behavior and non-English expectations with maintainers; done means glossary references support the agreed behavior and it is covered by documentation and tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.