[FOLIO-903] Add RAML files to api docs configuration for generate-api-docs Created: 22/Dec/16  Updated: 17/Dec/20

Status: Open
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: ongoing, raml
Remaining Estimate: Not Specified
Time Spent: 3 days, 1 hour, 50 minutes
Original estimate: Not Specified

Issue links:
Relates
relates to FOLIO-1253 Improve the generate-api-docs CI job In Progress
relates to FOLIO-541 split backend module projects into it... Closed
relates to FOLIO-1497 Improve the lint-raml CI job Closed
relates to FOLIO-1592 Improve the table-of-contents for API... Closed
relates to FOLIO-2922 Automate the configuration of API doc... Closed
Sprint:
Development Team: FOLIO DevOps

 Description   

For the generate-api-docs raml2html job, we do not have an automated way to configure the RAML files that are to be processed (and some repositories have a non-standard layout). Manually add to the configuration at folio-org.github.io/_data/api.yml (see notes).



 Comments   
Comment by David Crossley [ 29/Dec/16 ]

To assist this task, there is now a tool to scan local git checkouts to find RAMLs that are missing from the configuration and old ones that are no longer used:
generate-api-docs/find_new_ramls.py

Comment by David Crossley [ 12/Jan/17 ]

Closing this. However it is an ongoing task. I have that find_new_ramls.py script running locally via cron.

Comment by David Crossley [ 19/Jan/17 ]

The tenant.raml moved from "raml-module-builder" to a new shared section in the "raml" repo.

John Malconian Do you need to configure Jenkins for the "generate_api_docs.py" when new repos are added to the configuration, such as this?

Comment by David Crossley [ 24/Jan/17 ]

tenant.raml has been published

Comment by David Crossley [ 21/Feb/17 ]

Added configuration for mod-auth.

John Malconian Please add to Jenkins.

Comment by John Malconian [ 22/Feb/17 ]

Added. However, it does not seem to be picking up the raml for the permissions module - only the login module. I'm running it like this in the top-level directory of mod-auth:

python3 /usr/local/bin/generate_api_docs.py -r mod-auth -v -o $

{JENKINS_WORKSPACE}

/folio-api-docs

if [ $? -eq 0 ]; then
aws s3 sync folio-api-docs s3://foliodocs/api
fi

Comment by John Malconian [ 22/Feb/17 ]

Looks like the permissions module directory output is located under the login module directory. Here's what happens when I run manually from the top-level mod-auth directory:

python3 /usr/local/bin/generate_api_docs.py -r mod-auth -v -o folio-api-docs

Doing git clone recursive for 'mod-auth' ...
Processing RAML for mod-auth/login_module/ramls
Doing raml2html with login.raml into folio-api-docs/mod-auth/login_module/login.html ...
Processing RAML for mod-auth/permissions_module/ramls
Doing raml2html with permissions.raml into folio-api-docs/mod-auth/login_module/permissions_module/permissions.html ...

Is this how it should work? I think we want folio-api-docs/mod-auth/permissions_module/permissions.html instead.

Comment by David Crossley [ 22/Feb/17 ]

Eeek, so sloppy. Fixed now. Thanks.

The mod-metadata suffered the same.

Comment by David Crossley [ 25/Apr/17 ]

Re-open. Need to follow the FOLIO-541 Closed splitting of GitHub repositories. Adjust the api.yml configuration to match, as each is done.

Comment by David Crossley [ 27/Apr/17 ]

Done mod-loan-storage to mod-circulation-storage

Comment by David Crossley [ 27/Apr/17 ]

Added mod-login and mod-permissions

Comment by David Crossley [ 02/May/17 ]

Added mod-inventory and mod-inventory-storage

Comment by David Crossley [ 02/May/17 ]

Closed again, following completion of split of some git modules. This general issue is still an ongoing task (see notes above).

Comment by David Crossley [ 03/May/17 ]

John Malconian The configuration in api.yml has been adjusted for the recently split modules. Please enable the raml2html generation job for those.

Comment by David Crossley [ 24/May/17 ]

Removed configuration for user-related api docs (mod-login, mod-permissions, mod-users) which are now moved to folio-org/raml (raml-util).

Removed configuration for mod-users-bl until ready.

John Malconian do you need to remove the Jenkins trigger of generate-api-docs for those?

Kurt Nordstrom does the ./ramls directory now need to be removed for those first three modules?

Comment by John Malconian [ 24/May/17 ]

Removed doc generation build step from Jenkins for mod-login, mod-perms, and mod-users. Disable step for mod-users-bl for now.

Comment by David Crossley [ 11/Jul/18 ]

Back in May 2017 we moved various shared RAMLs to the "raml" repository. The API docs are generated for the master of that repository, so that does provide up-to-date shared API docs.

However the actual "raml-util" git submodule that is in use for each of those repositories (e.g. mod-users, mod-login, mod-codex-inventory, etc.) is not necessarily the current one. So their generated API docs could potentially be a little misleading.

So the configuration should be altered, so as to generate the docs from their actual master branch and so their own raml-util.

This also enables linking directly to their API docs table (e.g. as for mod-notes).

This also enables access to their ModuleDescriptor by the generate-api-docs CI job, if that is the best way to address FOLIO-1316 Closed cross-references.

Comment by David Crossley [ 11/Jul/18 ]

Scrap that idea. The generate-api-docs job would operate properly. However the API docs tables cannot link back to each actual RAML file, as they are in a version of the shared raml repository instead.

Comment by David Crossley [ 24/Jul/18 ]

I found a way to link the API docs tables to those raml files, so proceeded.

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