[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: |
|
||||||||||||||||||||||||
| 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: |
| 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 |
| 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' ... 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
|
| 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
|
| 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. |