Support Dynamic Document Injection

[shimizukawa]

Sphinx is a great tool. However, the need to create rst documents on disk prior to running sphinx-build is a bit inflexible. Sphinx-apidoc works around this limitation by requiring a separate script execution to manage api rst files. While this works, it requires extra steps and maintenance of the on-disk rst files, and additional tools like sphinx-apidoc for each set of dynamic documents generated.

I propose an enhancement to support dynamic document/doctree or perhaps even raw rst injection during sphinx-build execution. Ideally, this would be a hook or similar mechanism that extensions could use to inject documents prior to builder processing.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1139
• Originally reported by: Bob Ziuchkovski
• Originally created at: 2013-04-08T21:35:48.477

[webknjaz]

I was wondering about the same problem and tried to return a non-existent document name from the callback for env-get-outdated in hope that I'd catch it later via source-read and return some generated content. But it seems to be silently ignored and is not on the docnames list even in the next event that's happening (env-before-read-docs).
I guess Sphinx excludes invalid doc names right after that event. I'm curious if it could be preserved...

[tk0miya]

Sphinx expects that the filenames that extension returns via env-get-outdated event exist in the file system. At present, there is no way to pass the non-existent documents from extensions.

[webknjaz]

Could you point out where this check happens, please? I'd like to check how hard would it be to improve it.

[tk0miya]

Here:

sphinx/sphinx/builders/__init__.py

Lines 378 to 379 in 4c91c03

	for docs in self.events.emit('env-get-outdated', self.env, added, changed, removed):
	changed.update(set(docs) & self.env.found_docs)

The filenames given from event handlers are compared with found_docs to filter non-existent documents.

[webknjaz]

@tk0miya thanks! Would it be out of line to mutate what found_docs returns from an event handler?

[tk0miya]

I'm not sure what will be happened if this line accepts non-existent files. I guess many Sphinx components expect the file must exist. So we have to check whole of Sphinx.