[FOLIO-1592] Improve the table-of-contents for API Documentation reference Created: 23/Oct/18 Updated: 12/Nov/18 Resolved: 09/Nov/18 |
|
| Status: | Closed |
| Project: | FOLIO |
| Components: | None |
| Affects versions: | None |
| Fix versions: | None |
| Type: | New Feature | Priority: | P3 |
| Reporter: | David Crossley | Assignee: | David Crossley |
| Resolution: | Done | Votes: | 0 |
| Labels: | devweb | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original estimate: | Not Specified | ||
| Issue links: |
|
||||||||
| Sprint: | |||||||||
| Description |
|
The dev.folio.org/reference/api/ list of raml-related back-end modules has suddenly increased in number (now 44 on 2018-10-23). The left-hand ToC becomes cumbersome. Find a way to group them. |
| Comments |
| Comment by David Crossley [ 23/Oct/18 ] |
|
The ToC is automatically generated by tocbot JS using the h1..h4 html headings in the page content. The page is generated from the _data/api.yml data file, by the Liquid programming language behind /reference/api/index.md (which has some limitations, but can utilise Ruby plugins (and home-grown) and other data files). Each module entry in the list is added to the page as an h3 heading and associated table. Encompassing groups of modules in an h2 heading will enable the ToC to automatically expand and collapse for each group. How to group them? Some possible solutions: A) Functional categories. Add a "category" parameter to each entry in the api.yml configuration file. Defining the list of relevant categories is the difficult part. Leaving this solution until later. Perhaps utilise categories from the upcoming "App store". Or commence a set of categories, and modify later. B) Alphabetic groups. The Liquid could automatically split the list into equal-sized groups based on module name: Modules A, Modules B, etc. Probably sort each "edge-" one with the relevant "mod-" ones. C) Batches. The Liquid could automatically split the list into equal-sized batches, just crudely splitting sequentially into sets of say 6 modules. The api.yml list would have similar function modules ordered near each other to assist the batching. |
| Comment by David Crossley [ 23/Oct/18 ] |
|
Option C is the easiest and more useful than Option B, so doing that for now. |
| Comment by David Crossley [ 23/Oct/18 ] |
|
Also investigating ways to automate and delegate the configuration. |
| Comment by David Crossley [ 05/Nov/18 ] |
|
Now done Option A. Using list of groups in _data/apigroup.yml |