Split the appendices into multiple pages and include a table of contents in each

[larsgrefer]

The "Appendices" section in the new documentation has no table of contents which makes the whole page very hard to use: https://docs.spring.io/spring-boot/docs/2.2.0.M1/reference/html/appendix.html#appendix

All other pages seem to have a table of contents on their left side, which always highlights the current headline: https://docs.spring.io/spring-boot/docs/2.2.0.M1/reference/html/howto.html#howto-database-initialization
This gives a good overview over the whole page and makes the navigation very easy. The "Appendices" page however is pretty hard to navigate and orientate on.

In the "old" documentation the Appendices took part in the global table of contents.

[viktoriya-kutsarova]

Can I take this issue?

[bclozel]

I'm wondering if we should add a TOC there, or if we should go back to splitting the appendix into pieces. The appendix page is just huge, with a lot of auto-generated content. Not very friendly to people (nor browsers).

We could:

• turn this page into a page listing all the appendix topics. We'd need to rewrite include directives into links and add short descriptions for each. A bit like documentation-overview.adoc, but with more details?
• fix the advanced topics section which seem to miss a few appendix topics
• as a result, update the various links in the documentation pointing there (basically rewrite the commit 3428c0e, but this time pointing to individual pages instead of appendix.adoc#section)

I'll stick a team-attention label on this issue to get the team's opinion.

@viktoriya-kutsarova if the team agrees and if you'd still like to contribute this change, I'd be happy to provide guidance/pointers!

[larsgrefer]

Some additional ideas:

• The properties appendix could be a bit less "huge" by going back to a .properties-file style instead of the current (2.2.0.M1) table like this: https://docs.joinfaces.org/4.0.3/reference/#properties

• I think the documentation overview page would be a better index page than the actual index page.

[viktoriya-kutsarova]

@bclozel Sure, just let me know what you have decided!

[bclozel]

The team discussed this and we'd like to bring back the TOC anyway, but also consider breaking up the appendix page. We first need to consider #16295 to figure out if we'll have linking issues.

Once #16295 is done, we can resume work here and even solve #16267 at the same time: we should break up a bit more the large tables of configuration properties and see how the TOC will look like.

[bclozel]

@viktoriya-kutsarova #16295 is now done - we have some infrastructure problems with our CI right now, so that change is not reflected in the latest docs.

If you've performed a full build already, you can quickly generate the documentation with mvn prepare-package -DskipTests -Dfull in the "spring-boot-docs" module (you can even kill the process when it's done with the asciidoctor docs and working on the javadocs).

To summarize again:

• turn this page into a page listing all the appendix topics. We'd need to rewrite include directives into links and add short descriptions for each. At the adoc level, we could split the appendix.adoc into multiple files under an appendix folder. A bit like documentation-overview.adoc, but with more details?
• fix the advanced topics section which seem to miss a few appendix topics
• as a result, update the various links in the documentation pointing there (basically rewrite the commit 3428c0e, but this time pointing to individual pages instead of appendix.adoc#section)

Let me know if you've got time to work on this and how I can assist.

[viktoriya-kutsarova]

@bclozel Sorry for the late response! I can check it during the weekend and then let you know if I need any help!

[viktoriya-kutsarova]

I am summarizing what I understood from your comment, @bclozel. Correct me if something is wrong and I will start with the implementation.

• for the appendix listings - you mean to replace the include directives with links (something like the table of content of the documentation-overview.adoc that leads to the 6 subsections of the appendix?)
• for the advanced topics - just adding references to configuration-metadata, test-auto-configuration and dependency-versions (this should be the missing ones)
• the last one is to just update all references with the newly introduces structures

[bclozel]

Hey @viktoriya-kutsarova

1. Good question. This got me to think that we need different versions for the single/multi pages docs.
   So I think we should copy appendix.adoc to appendix-index.adoc and replace include directives with links in that new file. Then index.adoc should link to appendix-index.adoc. This means that the multi-page version will have that index while the single page version will keep things as is. We'll see if we need to copy the index structure to the single page version.

You're right on 2) and 3).