[FOLIO-1833] Spike: Create brief demonstration of RAML ability to use Markdown documentation Created: 28/Feb/19 Updated: 03/Jun/20 Resolved: 06/Mar/19 |
|
| Status: | Closed |
| Project: | FOLIO |
| Components: | None |
| Affects versions: | None |
| Fix versions: | None |
| Type: | Task | Priority: | P3 |
| Reporter: | David Crossley | Assignee: | David Crossley |
| Resolution: | Done | Votes: | 0 |
| Labels: | platform-backlog, raml | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original estimate: | Not Specified | ||
| Attachments: |
|
| Sprint: | Core: Platform - Sprint 58 |
| Story Points: | 1 |
| Development Team: | Core: Platform |
| Description |
|
The RAML files can utilise multiple "documentation" nodes using content in Markdown format. It can be in-line, or included via separate files located locally to the module's RAMLs. Some top-level files could also be included from the shared "raml-util" repository. Create a basic demonstration. |
| Comments |
| Comment by David Crossley [ 01/Mar/19 ] |
|
See the branch https://github.com/folio-org/mod-notes/tree/folio-1833-raml-markdown The file 'mod-notes/ramls/note.raml' has been edited to add more documentation at various levels. Some uses in-line documentation, some are included via separate files. The generated output documentation is not processed by Jenkins CI for a branch, only for master. See the locally generated documentation attached to this ticket. Each additional documentation snippet is prefixed with text FOLIO-1833 demo so search input and output for that term. The generated output documentation uses "raml2html themes". The "view-1" uses the default theme. The "view-2" uses the "Plain theme" and we have a fork of that with a couple of basic enhancements. More could be done, plus improved CSS. At the top of the RAML file there is "baseUri" and "version". These nodes are currently under-utilised, and often incorrect and confusing. There are some basic Jira tickets to improve those. To tweak the demo checkout the branch, and do local RAML/Schema validation and documentation generation using a local clone of lint-raml and generate-api-docs. |
| Comment by Jakub Skoczen [ 04/Mar/19 ] |
|
Mike Gorrell please review this issue so David can resolve it. |
| Comment by David Crossley [ 05/Mar/19 ] |
|
Refer to the "RAML 1.0 specification" regarding Markdown, and use find-in-page "markdown" to show where it can be utilised. |
| Comment by David Crossley [ 06/Mar/19 ] |
|
Closed. The demo is sufficient to provide some examples. |
| Comment by Mike Taylor [ 15/Nov/19 ] |
|
For the record: I have used these facilities to add a discursive introduction to the Course Reserves API. You can see the simple change I made at https://github.com/folio-org/mod-courses/commit/0001247c1e4d663745ae0477174bc8f89db189b4 and view the results in the mod-courses section at https://dev.folio.org/reference/api/#mod-courses I have often felt that auto-generated docs are of very low utility because they give no context about why one would use a given type or API. This kind of brief scene-setting prose can make a world of difference. I hope we get into a habit of doing this. |