sphinx-doc / sphinx-doc/sphinx
Reading from generated files not stored in the source directory or filesystem at all
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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