-
-
Notifications
You must be signed in to change notification settings - Fork 289
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[RFC, v3] Switching intermediate output from Markdown to YAML (aka Project Camel) #105
Comments
BTW, if anyone wants to check out the existing work on v2, here you go: https://scribe.readthedocs.io/en/v2/migrating-v2.html. It's not officially released yet, but you can try it with the |
Hi @shalvah look I personally dislike YAML, but this really sounds like an overall win and potentially solves a lot of the minor niggles I have had so far. I really appreciate all the work you are putting into this lib. |
I've decided to spend some time to develop this for v3. I'll release v2 in the next week or so, and begin work on v3. |
🎉v3 is out now, with all the improvements of Project Camel! |
Amazing! |
What is this?
Project Camel is a move to switch Scribe's processing from
[extract -> Markdown -> HTML (via Pastel)]
to[extract -> YAML -> HTML]
. In this model, Scribe will extract API and endpoints information and write that to a set of YAML files in a structured format, then it will transform these files into the usual HTML/Postman/OpenAPI outputs.Why?
The main goal is to not limit you. Scribe wants to help you generate great docs, and part of that is acknowledging that it can't do everything, and making it easier for you to change/add things the package misses. The structured format allows for greater flexibility (see the section on "Benefits" below).
Implementation
When you run
scribe:generate
a. Scribe will extract API and endpoints information and hold in memory.
b. Scribe will write the data to new data files and "compare files" (identical files used to compare on a future run to know what changed).
c. Scribe will transform the data it has in memory (not the data files) into the HTML/Postman/OpenAPI outputs. (It uses data it has rather than loading the data files as a speed optimisation.) END.
a. If
--force
is set: Scribe will extract data, overwrite the data files and compare files, and continue to the usual outputs. END.b. If
--force
is not set:Yaml::parse()
into PHP arrays, not just reading the file contents.)With
--no-extraction
:--no-extraction
requires the data files to be present. Scribe will load the data files and transform them to Markdown.Note that the data files are loaded before route extraction is done. This allows us to skip extracting data for any routes that have been modified.
Here's what a group file could look like.
Benefits
groups/
directory.. To order endpoints within a group, just edit the YAML file for the group and rearrange them. Scribe will respect that order on the next run (except you `--force). Groups are written to numbered files, and you can re-number them to sort the groups.scribe.php
,output.css.include
to include extra styles,output.head.append
to add scripts at the end of the HEAD tag, etc.Cons
intro_text
, endpoint descriptions) has to be manually passed through a Markdown-to-HTML parser.This approach won't work well when you change a group name in your code. The old group file from the last run would still be present in the directory and get included in the docs. The existing Markdown approach always deletes any Markdown files that were not created in this run in theSolution: Before writing data files, Scribe will read the last known groups from the compare files and delete any that can't be found in the data files. Users add custom groups ingroups/
directory. But we want the users to be able to add extra groups if they wish. Maybe we'll keep that approach. The user shouldn't add any new group files. Instead, they can add a new group into any existing group file..custom.yaml
files within the data dir.Considerations
This makes things too complicated.
Not really. It's just as complicated as the current setup, only different. Also, the aim is to hide as much complexity as possible until the user needs it. For instance, unless you want to change something in the endpoints' data or add an endpoint, you shouldn't need to touch the YAML files at all.
Why not write to (and read from) a standard format such as OpenAPI?
OpenAPI is a spec that describes how APIs should be written, not necessarily how they are. For instance, it does not support optional path parameters. Also, parsing OpenAPI into the proper route information is complicated, because of its strict format. Finally, you can't store examples and other presentation info in OpenAPI. 😕
Why YAML?
It's the most readable out there, and I want users to not feel intimidated when they dive in to these files. It's got some hiccups writing-wise, but they should be able to handle that.
The text was updated successfully, but these errors were encountered: