[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: Zip Archive folio-1833-sources.zip     HTML File view-1.html     HTML File view-2.html    
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.

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