Auto-detect the amount of renderPasses needed

[balupton]

DocPad allows documents to reference each other - for example display listing of blog posts, or including the result of one file in another file.

So far we have handled this by doing a two pass render (so re rendering everything twice), however for references deeper than one, the 2 pass render is not enough (e.g. document b requires a, and document c requires b - in this example, document c wouldn't render correctly, however document b would - we would need a 3 pass render to do this).

We need a way to more intelligently handle these situations.

Issues to consider:

1. How should we handle circular references? From all my thoughts it seems impossible to handle this correctly, as such we should perhaps just error - see http://stackoverflow.com/q/13657311/130638 - however, circular references are only an issue if we are after the rendered content of the circular reference - if we are just after the meta data of it, then two pass is fine - we currently have no way of distinguishing this, however it's probably possible.
2. Is it possible to intelligently render things in a particular order to minimise the amount of rendering required?
3. We currently know which documents contain references to other documents via the auto set referencesOthers flag, however we currently do not have a way to know what documents a document references - is possible to add this though.

Work is being done on this on the dev-render branch.

---

Want to back this issue? Place a bounty on it! We accept bounties via Bountysource.

[balupton]

Use cases which pop up a lot.

Menus

Your layout does a listing of all the pages you have. Each page uses that layout. Therefore each page refers to itself. Possible if just referring meta data, if referring rendered content, impossible.

Listings

Doing a blog post listing that contains all the rendered content of the blog posts. One level of reference (listing to posts). References use rendered content.

Combining Examples

Ran into this when writing API documentation for some client work. Had the issue where B uses A, C uses B, D uses C which fails on the two pass render as there are 3 levels of reference, not just one. References use rendered content.

[balupton]

Okay, so DocPad v6.16 now lets you customise how many renderPasses are required.

A big change here over the way things were previously done is that we now split the initial render batch into two parts - rendering everything that doesn't reference others, then rendering everything that does reference others - and any subsequent passes will only re-render things that do reference others.

It's a good step forward, but an intelligent algorithm for building up a single render pass remains ideal.