[wp-meta] [Making WordPress.org] #1802: Restructure reference pages more logically and apply the TOC to allthethings

[Making WordPress.org]

#1802: Restructure reference pages more logically and apply the TOC to
allthethings
---------------------------+-----------------
 Reporter:  DrewAPicture   |      Owner:
     Type:  enhancement    |     Status:  new
 Priority:  normal         |  Milestone:
Component:  Developer Hub  |   Keywords:
---------------------------+-----------------
 In [3563] for #1548, we implemented a table of contents for the
 explanation or "More Information" section of reference pages. With this
 ticket I'm proposing three extensions of that effort:

 1. Apply the table of contents to most if not all of the sections of any
 given reference page
 2. Slightly restructure the reference page sections and in some cases
 consolidate to provide a more logical flow of information within that
 table of contents.
 3. Slightly modify the TOC class in the handbook plugin to accept dynamic
 header text, defaulting to 'Topics'.

 For !#1, making it possible to apply the table of contents logic to
 multiple reference page sections requires splitting that content into
 pieces. My attached patch proposes splitting them all into individual
 template parts that we therefore capture in output buffering to output all
 at once.

 For !#2, I've also slightly restructured the ordering and consolidation of
 information, namely, made "Description" the top-level section, and moved
 Parameters, Return, Source, and Changelog under "Description". I've
 consolidate to two Source sections into one.

 I've also grouped Uses and Used By under a new top-level "Related" section
 that we can further extend in the future with related functionality.

 Finally this leaves us with roughly four top-level sections for any given
 reference page: Description, More Information, Related, and User
 Contributed Notes.

 Before and after screenshots attached.

--
Ticket URL: <https://meta.trac.wordpress.org/ticket/1802>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org