parser-js
parser-js copied to clipboard
asyncapi
docs website for the api of the parser
Reason/Context
At the moment the API is sat in the Readme file https://github.com/asyncapi/parser-js/blob/master/API.md, which is fine and seems to work, but I wonder if we could bring our API alive?
Maybe it's just me, but when I interact with 3rd party libs, I find it very useful to have the website render the APIs with examples too for each function.
Here are some open-source examples of what I mean:
- https://date-fns.org/v2.25.0/docs/isDate
- https://jestjs.io/docs/puppeteer
- https://webdriver.io/docs/api/browser/deleteCookies
As you can see the general theme with these is:
- The API is listed down the side
- Clear docs + examples for each function which is nice
Most of them use https://docusaurus.io/showcase which we might be able to use too, or maybe somehow add it to the AsyncAPI website, not sure.
Why do we need this improvement?
Make the API more accessible with examples and docs to go with the APIs, just be easier to get up and running, and search for things.
Wondered what you all think?
Eventually, we should have any tools docs published on the website. The website should not only host specification docs but tools docs too. We just never had time to have it done 😞
Hmm yeah, interesting, I wonder if we could use ISR or SSR to pull down the API.md file from the project and render out the functions and examples.
imho we should follow push, not pull approach. My previous experience shows such an approach is more efficient.
by push I mean a workflow on parser-js repo, that notices changes to API.md file and pushes them out to website repo as a PR that is automatically merged by the bot. This is how we handle updates in specification MD file in website that always reflects latest spec document from spec repo. The same way we update list of TSC members on the website, with this workflow.
I like this idea @derberg, is that what you mean (following the example here)
- Website has its own local copy of API.md
- Website renders stuff from the file.
- Changes are made to API.md file workflow picks it up and pushes new copy to website
- Website reviewed/merged and updated.
Is this the kind of idea you have?
Exactly, might be that some tuning of the API.md file must be done inside the workflow, as we do with spec file.
but I guess API.md is not the only one, right? would be nice to have stuff that are already in the readme, might be that we need to pull these out to separate markdown files to handle them the same was as API.md?
and in future the same with generator and the whole rest 💪🏼
the question is where does it go? https://www.asyncapi.com/docs/tools/parser-js/ ? and https://www.asyncapi.com/docs/tools/ should list all the others? and left nav should be the same as we have here https://www.asyncapi.com/docs/getting-started ?
@alequetzalli this is definitely a topic for ya where your voice is super important 😄 yet another one 😄
Yeah I think the left nav idea should good and lists the functions etc from the README file, I have no idea how we can add examples to the functions.
As a dev I would love to see the function and maybe exampels with each API.... maybe this can be done in the API.md file no idea....
Seems like we have some standard urls atm:
- https://www.asyncapi.com/tools/parsers
- https://www.asyncapi.com/tools/modelina
- https://www.asyncapi.com/tools/github-actions
Which I assume is https://www.asyncapi.com/tools/{tool} so maybe something like https://www.asyncapi.com/tools/{tool}/docs would be good?
Example https://www.asyncapi.com/tools/parsers/docs would render the docs for each tool.
but I guess API.md is not the only one, right? would be nice to have stuff that are already in the readme, might be that we need to pull these out to separate markdown files to handle them the same was as API.md?
Sorry, not sure if I understand what you mean here
I have no idea how we can add examples to the functions.
possible, have a look at this
Example https://www.asyncapi.com/tools/parsers/docs would render the docs for each tool.
you mean render navigation with docs for each tool? but render content of first default document for specific parser parser?
Sorry, not sure if I understand what you mean here
It is not only about API and Examples. When you go to the readme you see much more important information:
- errors handling
- custom parser spec extensions
- handling circular refs
- adding custom schema parsers
We need these to be in the docs section too
the question is where does it go?
https://www.asyncapi.com/docs/tools/parser-js/? andhttps://www.asyncapi.com/docs/tools/should list all the others? and left nav should be the same as we have here https://www.asyncapi.com/docs/getting-started ?@alequetzalli this is definitely a topic for ya where your voice is super important 😄 yet another one 😄
Yes! According to our content buckets from the Diátaxis Framework that we're using to re-structure our IA of the Docs, all of these API docs go under Reference. These API docs and others should be moved under our Docs site, and we need to select an API tool to generate nice API docs. I don't know why we can't just use swagger or something similar, then tailor the CSS to our brand needs?
The look of API reference docs in our site is something we'll need to bring Missy Turco in, does she have a GH handle we can tag her into these convos in? 🤔
I want us to start thinking about moving toward nicer and cleaner URLs, such as:
-
https://docs.asyncapi.com/concepts/traits -
https://docs.asyncapi.com/tutorials/streetlights -
https://docs.asyncapi.com/reference/parser-js -
https://docs.asyncapi.com/reference/modelina
(yes, this means 301 re-direct setups, already a convo I've told Lukasz I want to tackle in my 1st year here as part of the needed IA changes)
The /tools section will not live where it currently resides, it needs to be moved to another appropriate content bucket. SDK docs for Modelina should go under broader content bucket Reference.
all of these API docs go under Reference
do we really have to mix spec docs with tools docs? imho these are separate things. Separate in the way that Modelina has its own content buckets and nobody looking for Modelina should go into spec docs, you know what I mean?
Also it is not just API docs, it is also examples, some additional descriptions, more details, even some tutorials
I don't know why we can't just use swagger or something similar, then tailor the CSS to our brand needs?
we talk about library API, in case of Modelina it is an API that JavaScript or TypeScript developer would need to understand what methods to use, etc. So nothing that swagger/openapi can help with, as these are for describing REST API.
The only place where we need OpenAPI so far is https://github.com/asyncapi/server-api/pull/2
The look of API reference docs in our site is something we'll need to bring Missy Turco in, does she have a GH handle we can tag her into these convos in?
I bet she has one, but you will know it only if you ask her 😄
I want us to start thinking about moving toward nicer and cleaner URLs
maybe it is the right time to open up an issue about it
I'm going to spend some time seeing how I can use our existing doc build approach (markdown files + MDX generation) and see how it can support us for tools.
I have something working locally, and a pattern I believe can really help, but let me get a draft PR into the website repo, and see what you all think, and maybe we can take things from there.
OK think I got some POC together and a video you can watch over on Slack: https://asyncapi.slack.com/archives/CQVJXFNQL/p1635171970029500
Would love to know your thoughts.
Also it is not just API docs, it is also examples, some additional descriptions, more details, even some tutorials
Yeah, the Tools might just need to have their own section but we still need to plan this further. The current tool section leaves much to be desired and isn't an actual Tools section.
I mention swagger to generate the basic styling for the GET/PUT/etc call boxes and copy. Unless we want to do it all from scratch or use another similar solution/package, but we regardless need to implement something.
I am seeing kind of a mess when it comes to the info around tooling. Any tutorial or info in Docs about our Tooling is not a dumping ground (like it currently is), it needs to be well explained and there needs to be a central location for it all.
The IA changes coming also apply to how we document our Tools.
maybe it is the right time to open up an issue about it
I will open one once I am closer to actually making that change. I need us to agree to an improved IA before I update URLs. URL story comes after that.
OK think I got some POC together and a video you can watch over on Slack: https://asyncapi.slack.com/archives/CQVJXFNQL/p1635171970029500
Would love to know your thoughts.
Hmmm... I am curious about a variation of this, but not the current implementation example shown in this video. This video shows how to pull the doc from what is written in a given project's README file. README files are not even CLOSE to documentation standards for a Docs site. I would never rely solely on pulling from a README. So that I cannot get behind, that's what engineers typically do when they do not have an actual Docs team.
The purpose of a new article/post or section in a Docs site is very diff from the purpose of an informal README. I just want to make sure we don't lose that insight. The way I write sections and divide content on a README is a completely different strategy from the way I write a new Doc in a Docs site.
I'm all for automizing tasks that do not need to be done manually by a human and integrating GH Actions and such.. but we must remember that quality and educational docs for Tools will not come from a README alone.
@magicmatatjahu you might want to jump in here in regards to "relative links" that we have in markdown files and how we solve these in the UI. @boyney123 we did something similar in our previous project, Kyma, and we used a component that did Markdown -> HTML rendering on the client, and we could have hooks to modify stuff, like for example <a> tags to modify links.
@derberg yeah was just thinking about that this morning, I have done similar stuff in the past which reads markdown files and replaces relative links with the correct ones.... I guess that is one way to do it but good to hear other ways
My initial thoughts are
- Get the
docs(markdown files) - Fix all the links on them (change relative links to absolute or something, depending on the context of the link)
- Render docs as usual
The fixing links part will be part of the build step... maybe.
Dunno not thought too much about it 🤣
sounds good so far
The fixing links part will be part of the build step... maybe.
build step is the best as with Next.js even rendering react is done on a build level. In the solution I described above we used Gatsby, but the principal was the same. So even if I write, markdown -> HTML with links fixing was on a client-side, eventually it was during the build and getting static content out of the build process. MDX has plugins system, I bet it can be used to plugin into the process of rendering and fix the links on the fly
MDX has plugins system, I bet it can be used to plugin into the process of rendering and fix the links on the fly
I would prefer that idea than changing the links by some script. We can change link here on the fly on rendering phase and also on client side https://github.com/asyncapi/website/blob/master/pages/_app.js#L50
This issue has been automatically marked as stale because it has not had recent activity :sleeping:
It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.
There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.
Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.
Thank you for your patience :heart:
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
This issue has been automatically marked as stale because it has not had recent activity :sleeping:
It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.
There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.
Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.
Thank you for your patience :heart:
This issue has been automatically marked as stale because it has not had recent activity :sleeping:
It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.
There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.
Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.
Thank you for your patience :heart: