sphinx-doc / sphinx-doc/sphinx

Reading from generated files not stored in the source directory or filesystem at all

Open
#10,641 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Currently, extensions like autosummary write files directly to the source directory in the builder-inited step, in order to then allow them to be processed as additional documents.

In general it is inconvenient to write to the source directory:

  • Source directory might be read-only
  • Issues with multiple builds happening concurrently from the same directory
  • Users might accidentally check these generated files into source control.
  • Need care to avoid accidentally clobbering files that should not be clobbered while still being able to overwrite an existing generated file.

It would be better if extensions could generate "virtual" source documents, that are processed like any other document in the source directory but are just stored in memory and never need to be written to the filesystem.

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 tracing how extensions such as autosummary generate files during the builder-inited step and how those files enter document processing. Define and implement a virtual-source-document path that processes generated documents without writing them to the source directory, including behavior for concurrent builds and overwrites.

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
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.