[FOLIO-1253] Improve the generate-api-docs CI job Created: 18/May/18  Updated: 18/Dec/20

Status: In Progress
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Task Priority: P3
Reporter: David Crossley Assignee: David Crossley
Resolution: Unresolved Votes: 0
Labels: devweb, raml
Remaining Estimate: Not Specified
Time Spent: 3 days, 7 hours, 40 minutes
Original estimate: Not Specified

Issue links:
Relates
relates to FOLIO-1392 Enable the generate-api-docs CI job t... Closed
relates to FOLIO-2898 Create folio-tools/api-doc, from RAML... Closed
relates to FOLIO-903 Add RAML files to api docs configurat... Open
relates to FOLIO-1645 Configuration of locations of RAMLs a... Open
Sprint:

 Description   

The script that generates the API docs could use some improvements.

e.g. not require explicit configuration of each of the raml files.



 Comments   
Comment by David Crossley [ 28/May/18 ]

In folio-tools/pull/2 done stage one of improvements:

  • general tidy
  • added command-line arg "loglevel" and deprecated the "verbose"
  • ensure that input files exist and warn when missing
  • added configuration option to exclude specific directories and files
  • find and process any files that are not configured, and warn about missing
  • generate a configuration file with the gathered metadata

Next steps:

  • gather the generated configuration files for each repo and amalgamate them
  • use that amalgamated config at dev.f.o to generate the listing front page
  • enable use of either RAML-0.8 or RAML-1.0
Comment by David Crossley [ 31/May/18 ]

The script now detects whether the input file is RAML-1.0 or RAML-0.8 and uses the relevant version of raml2html. The RAML-0.8 needs raml2html v3, and RAML-1.0 needs 4+ currently v7.

The RAML-1.0 docs cannot use raml-fleece which currently generates the second "view-2" at https://dev.folio.org/reference/api/
So next job is to gather the generated configuration files and improve that front page.

The current raml2html can use templates and themes, so we can now enhance our views of the API docs.

Anyway, now ready to proceed with the first run, being the upcoming mod-kb-ebsco. Go Sobha Duvvuri.

Comment by Sobha Duvvuri [ 31/May/18 ]

Thanks David Crossley! We merged our changes to mod-kb-ebsco master and are able to successfully see docs here: https://s3.amazonaws.com/foliodocs/api/mod-kb-ebsco/eholdings.html#

Comment by David Crossley [ 02/Aug/18 ]

See "Enable the generate-api-docs CI job to save output for each software version" FOLIO-1392 Closed .

Still working on the automated configuration part of this FOLIO-1253 In Progress .

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