[FOLIO-589] Provide alternative views of the API docs Created: 08/May/17 Updated: 18/May/21 Resolved: 18/May/21 |
|
| 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, doc, raml | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | 2 days, 1 hour, 5 minutes | ||
| Original estimate: | Not Specified | ||
| Sprint: | |
| Development Team: | Core: Platform |
| Description |
|
We currently have the API docs automatically generated from the RAML files. This uses raml2html. There are useful improvements to that tool. However these are going into their v4+ versions (which is RAML-1.0 only). For the moment we need to stick with v3.x for RAML-0.8 version. The raml2html does use a template system, so we could improve the presentation. However it might be easier to wait until we are back on the current version. Some people prefer a presentation that uses a full html page for each api doc, rather than the pop-ups that default raml2html uses. Provide alternative views using other tools. There are not many available. Later settle on one or two of them, then enhance their templates. |
| Comments |
| Comment by David Crossley [ 08/May/17 ] |
|
Updated the folio-infrastructure/generate-api-docs to also use raml-fleece. John Malconian would you please update the server copy. |
| Comment by John Malconian [ 10/May/17 ] |
|
David Crossley Ok. I've updated the build image with the latest generate-api-docs directory contents and tested it on mod-inventory. Let me know if there are any issues. |
| Comment by David Crossley [ 10/May/17 ] |
|
Thanks for your efforts with deploying that. It works successfully. Now to proceed to the other modules. |
| Comment by David Crossley [ 03/Sep/18 ] |
|
For repositories that are now using RAML-1.0 version, the “view-2” presentation is not available because the "raml-fleece" software that is used to generate that view only supports RAML-0.8 version. So either find some other suitable software, or investigate the template system of current raml2html (which generates the "view-1" set) to produce other views. |
| Comment by David Crossley [ 20/Nov/18 ] |
|
Now using "raml2html-plain-theme" to generate the "view-2" (no pop-ups) for RAML-1.0 repositories. (The renewed front page will be presented after the cache updates for you.) As explained in the Usage notes the "view-2" link will be active for each such repo after their next merge to master re-generates the docs. |
| Comment by David Crossley [ 11/Dec/18 ] |
|
Using our folio-org fork of raml2html-plain-theme. So far only to show all resource-body divs. See folio-tools/pull/58 |