Two levels of nesting in reference index

[hadley]

For very long reference indexes (like keras). Ideally toc would expand/contract too. Could also imagine having a separate page for each top level section.

[AdrianHordyk]

FYI, another example of where multi-level nesting in reference index has been helpful.

Our DLMtool package has a large number of functions that belong to distinct categories. I added some dodgy hacks to build_preference a while ago to produce this (currently out-of-date). The key feature is having our 'Management Procedure' functions separate from the rest, although the further separation was helpful as well.

My hacked code has since broken with updates to pkgdown which is of course to be expected.

[hadley]

@jayhesselberth this seems like it might be worth revisiting now that we have a better TOC in the sidebar.

[jayhesselberth]

For keras, a second natural level could be for "Layers". Easiest way to implement would be to add a "group" section and nest titles under that. Groups would be assigned h2 and titles would get h3.

reference:
  - group: "Layers"
    - title: "Core Layers"
      contents:
      - layer_input
    ...
    - title: "Convolutional Layers"
      contents:
      - starts_with("layer_conv_")
    ...

Need to think about how this would work if no groups were specified, or if there were a mixture of groups with titles and just bare titles not associated with a group.

[hadley]

Maybe we could say that contents could also be a richer list?

reference:
- title: "Layers"
  contents:
  - title: "Core Layers"
    contents:
    - layer_input
    ...
  - title: "Convolutional Layers"
    contents:
    - starts_with("layer_conv_")
...

[hadley]

That would be a bit easier to work with if we used something other than title at the top-level:

reference:
- section: "Layers"
  contents:
  - title: "Core Layers"
    contents:
    - layer_input
    ...
  - title: "Convolutional Layers"
    contents:
    - starts_with("layer_conv_")
...

Then reference is always a list and each child must have either a section or a title element.

[hadley]

Or maybe make the special name go inside?

reference:
- title: "Layers"
  contents:
  - subtitle: "Core Layers"
    contents:
    - layer_input
    ...
  - subtitle: "Convolutional Layers"
    contents:
    - starts_with("layer_conv_")
...

Then title is always <h2> and subtitle is always <h3>

[jayhesselberth]

Another idea would be to enable a user-provided TOC spec for the reference. Would create the TOC by parsing the initial reference index html output, updating h2 (matching by title) and h3 (matching by subtitle) and inserting values from the spec into data-toc-text for each h2/h3.

In this case we wouldn't have to rewrite reference processing code, users wouldn't have to rewrite their reference index yaml, and the TOC spec might also be useful for articles.

reference:
- toc:
  section: "Layers"
  - title: "Core Layers"
  - title: "Convolutional Layers"

 ... original reference is unchanged ...

- title: "Core Layers"
  contents:
  - layer_input
    ...
- title: "Convolutional Layers"
  contents:
  - starts_with("layer_conv_")
    ...

[hadley]

My main concern with that approach is the matching is a bit tricky, and we'd have to think carefully about messaging so people could figure out why things were going wrong. Anyway, I'll have a play around over the next couple of days, and see how it feels with an implementation.

[hadley]

Yet another idea — we could flatten the yaml:

reference:
- title: "Layers"
- subtitle: "Core Layers"
- topics:
  - layer_input
- subtitle: "Convolutional Layers"
- topics:
  - starts_with("layer_conv_")

This would be a bigger change, but I think I'm going to do it internally because it makes the implementation simpler.

[hadley]

For now, I think we can leave at

reference:
- title: "Layers"
- subtitle: "Core Layers"
  contents:
  - layer_input
- subtitle: "Convolutional Layers"
  contents:
  - starts_with("layer_conv_")