Get the next/prev document for a document

[wouterj]

Feature request

This may well be something supported in Guides already and I missed it. So more of a "how would you approach this" discussion than a true feature request.

For symfony.com, we need to generate fjson files. These contain the HTML body and some metadata of the document, like its title and parents. It also includes the Previous and Next document. See wouterj/symfony-docs-guides#8 for my attempt to create a JSON renderer.

However, I have trouble finding the prev/next file for the currently rendered file. In the referenced PR, you can see my attempt of using DocumentListIterator. But this iterator seems to not be sorted according to the toctree (or the toctree order is wrong?).

Do we need to implement something to create an ordered list of documents early in the render phase? Or is this already done by Guides and should we expose this to the renderer somehow?

[jaapio]

@linawolf how is this done in Typo3 docs?

[linawolf]

We are doing it via twig functions currently.

There is an open PR where we think we might want to exclude orphans: TYPO3-Documentation/render-guides#1138

I dont remember in deteail how we implemented it but that might be a starting point

[wouterj]

Thanks for the link Lina!

Your Twig extension uses $renderContext->getIterator()->nextNode()?->getDocumentEntry(), it fetches the $renderContext from the Twig context. This is set by the Twig template renderer, which gets the render context from the RenderDocumentCommand. That one in turn gets it from the RenderHandler, which initializes the RenderContext.

I have the same code in my JsonRenderer, but my tests show that the documents aren't ordered properly. So either the document tree isn't ordered (but I'm confused why it is for Typo3), or the order is not the same as with Sphinx and the Doctrine Rst Parser. I'll investigate further outside of work hours :)

[linawolf]

I remember we did have trouble with the order, therefore I wrote extensive tests for that

[jaapio]

The order of the documents is determined by the document tree. Where the toctree directive has impact.

f72e199

I don't know exactly anymore what all the cavecats were, but I remember that @linawolf told me that toctree was a bit confusing in the way it restructures the documents in a documentation set.

[wouterj]

As it turns out, the json test I copy-pasted tested more advanced TOC ordering than I expected. Normal TOC behavior works as expected and the iterator is indeed sorted 👍

However, when a document is duplicated in multiple TOC trees, the ordering seems to be broken (or at least, not according to Sphinx's behavior). I've described this in more detail in #1277

Conclusion: we can close this issue, the document iterator provides the required API to get next/prev documents. Thanks for the useful pointers Lina and Jaap!