Spec Insert #8472
Spec Insert #8472
Conversation
nhtruong
requested review from
kolchfa-aws,
Naarcha-AWS,
vagimeli,
AMoo-Miki,
natebower,
dlvenable and
epugh
as code owners
|
Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Editorial review -> Merged. Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer. When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference). The doc reviewer will arrange for an editorial review. |
A program that insert API Components generated from the OpenSearch OpenAPI Spec into markdown files Signed-off-by: Theo Truong <[email protected]>
nhtruong
force-pushed
the
spec_insert_phase_1
branch
from
8234d31
to
611ddf7
Compare
There was a problem hiding this comment.
Code looks good. I made some nitpicks below, but at a higher level I think we should debate what form this takes.
I think it's important to not merge this without working CI/CD. I would say this is my one must have.
I think the tool should not be a command line processor nor a rake task. This project is already a Ruby project based on Jekyll that supports plugins. It would be better as a plugin because doc writers would run jekyll serve locally, and keep updating the docs, while Jekyll re-generates the pages that have changed in the background, no need to constantly run the tool command line. In an editor you'd see changes almost immediately get reloaded and can keep editing the document. Otherwise authors of the documentation have to know the special process of invoking the command and keep invoking it all the time. It's easy to disable the plugin when deploying the site too, and it could emit a warning that content may have changed. Finally, the plugin could (re)render only the pages that have changed, which is a lot faster.
I don't love the name. I think the tool will do more than use the spec, potentially applying other transformations like maybe running examples. Another idea for a name could be render.
| @@ -0,0 +1,25 @@ | |||
| require: rubocop-rake | |||
| AllCops: | |||
| Include: | |||
There was a problem hiding this comment.
Should apply to specs to, use rubocop -a ; rubocop --auto-gen-config in general.
| @@ -0,0 +1,91 @@ | |||
| # README: Spec Insert | |||
There was a problem hiding this comment.
| # README: Spec Insert | |
| # Spec Insert |
| - [Ignored files and folders](#ignored-files-and-folders) | ||
|
|
||
| ## What is this? | ||
| This program allows you to insert API components generated from the OpenSearch Specification into this repository's markdown files. It's still underdevelopment, and many features are not yet implemented. This document will be updated as the program evolves. |
There was a problem hiding this comment.
| This program allows you to insert API components generated from the OpenSearch Specification into this repository's markdown files. It's still underdevelopment, and many features are not yet implemented. This document will be updated as the program evolves. | |
| The spec_insert tool allows you to insert API components generated from the [OpenSearch Specification](https://github.com/opensearch-project/opensearch-api-specification) into this repository's markdown files. It's still underdevelopment, and many features are not yet implemented. This document will be updated as the program evolves. |
| 3. Install Ruby 3.1.0 or later. | ||
| 4. Install the required gems by running `bundle install`. | ||
|
|
||
| ## How to use |
There was a problem hiding this comment.
| ## How to use | |
| ## How to Use |
| ``` | ||
|
|
||
| ### Ignored files and folders | ||
| The program will ignore all markdown files whose names are in ALL CAPS. On top of that, you can also add files and folders you want to the [ignored.txt](./ignored.txt) file. Each line in the file should be the name of a file or folder you want to ignore. |
There was a problem hiding this comment.
Maybe we should name ignored.txt as .spec_insert_ignore to be consistent with gitignore and friends.
| 'https://github.com/opensearch-project/opensearch-api-specification' \ | ||
| '/releases/download/main-latest/opensearch-openapi.yaml ' \ | ||
| '-o opensearch-openapi.yaml' | ||
| end |
There was a problem hiding this comment.
Download to a temp or _site folder to avoid git add-ing it later.
Don't use sh curl, it will be harder to debug, may not work on Windows, etc.
openapi_url = "https://github.com/opensearch-project/opensearch-api-specification/releases/download/main-latest/opensearch-openapi.yaml"
openapi_path = "_site/opensearch-openapi.yaml"
File.write(openapi_path, URI.open(openapi_url).read)| root_folder: '../', | ||
| spec_file: './opensearch-openapi.yaml', | ||
| ignored: './ignored.txt' | ||
| ).insert_spec |
There was a problem hiding this comment.
rename the method to have a ! ruby-style, so insert!
|
Thanks @dblock |
Description
A Program to insert API components generated from OpenSearch Spec into markdown files.
Check out the included
README.mdfile for more details.Checklist
For more information on following Developer Certificate of Origin and signing off your commits, please check here.