sphinx-doc / sphinx-doc/sphinx

Allow builders to specify the Transforms

Open
#8,975 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Desired workflow
I created the restbuilder extension which recently gained some traction. It is typically used in this workflow:

  1. Documentation in reST with Sphinx-specific directives
  2. Run Sphinx with this reStructuredText Builder/Writer
  3. The result is documentation in reST with only doctree/"vanilla" directives
  4. Publish on e.g. GitHub (which understands reST, but not Sphinx-directives).

While refining the extension, I bumped into an issue with substitutions:

  • reStructuredText does not support nested markup, like italics in the name of a link, or inline images in a table.
  • The workaround is to use substitutions in reStructuredText.
  • Sphinx resolves these substitutions with the Substitutions Transform.
  • That's an issue, my writer needs the substitutions, not the nested markup.

Feature Request
I like my builder to be able to disable specific Transforms, in this case the Substitutions Transform.

Possible alternative
An alternative is to create a Transform that re-adds these substitutions, and apply them in the Writer (just before the Translator), rather than in the Reader.

Considerations
Currently, Sphinx is sharing doctrees between builders. This already is an issue, as reported in #8974. However, allowing builders to easily add or remove transforms will likely make that problem worse.

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

Start by reviewing the builder and reader transform lifecycle, then read the shared-doctree concern in issue #8974. Compare disabling the Substitutions Transform with re-adding substitutions later in the writer. Done means builders can control transforms without introducing incorrect shared doctrees.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.