Add an 'include-read' event

[AA-Turner]

closes #11648, #11643, #11620

cc: @mgeier @lmoureaux

The easy option would be to set the docname to self.env.docname (the current document being read), but this might throw off extensions that expect to only have "source-read" called exactly once per document.

Please test / let me know thoughts!

A

[AA-Turner]

I'm leaning towards the generated docname approach -- would appreciate your opinion @mgeier, as this solves the 'docname can be None' issue, but introduces docnames that don't work with doc2path().

A

[mgeier]

I think inventing a string (like 'include-from-mysource') is much worse than returning None.

If a string is returned, I would expect that string to be the document name.

I'm fine with returning None, but the documentation should be updated, as I mentioned in #11648.

[AA-Turner]

A good point -- I've also re-visited the original issue (#10678) and have thusly changed my mind -- this PR now introduces a new 'include-read' event, which no longer abuses the 'source-read' event for non-documents.

I assume this would work for your purposes?

A

[mgeier]

That sounds much cleaner!

I assume this would work for your purposes?

Yes, sure, an additional event will not break anything if I don't use it, right?

My extension sphinx-last-updated-by-git doesn't need an event for the include directive, it only needs to check the env.dependencies of every source file, which should contain the included files.

[mgeier]

I don't know if anyone needs this, but you could pass the parent document name to the event handler?

[AA-Turner]

Good shout!

[lucyleeow]

Thanks @AA-Turner, this is a good solution!