[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:
Relates
relates to FOLIO-903 Add RAML files to api docs configurat... Open
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

Generated at Thu Feb 08 23:14:28 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.