search

Mermade / widdershins

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown
https://mermade.github.io/reslate
MIT License
1.49k stars 320 forks source link

Docs: User Guides #243

Open evenstensberg opened 5 years ago

evenstensberg commented 5 years ago

Is your feature request related to a problem? Please describe. This project looks amazing, but I´m somewhat left with a no-clue of how I´m supposed to build up an API using this repository after the initial look. Is there any user guides about where to configure what and what to configure?

Describe the solution you'd like Documentation with a walkthrough of how-to, for instance, deploy to github pages

Describe alternatives you've considered Reading the source and the documentation Additional context I dunno if this is the right place to post, feel free to close if irrelevant. I´m working on an API for SSC Web (NASA Goddard) and this seems like a good tool to write the API in.

MikeRalphson commented 5 years ago

Definitely not irrelevant, I'll stub out something and link to it in this issue.

MikeRalphson commented 5 years ago

I'll add more to a separate doc soon, but I've added a Getting started section to the README as this was notably lacking.

BTW; :rocket: :sunglasses:

evenstensberg commented 5 years ago

HI, thanks! Do you think more definitive user guides would be a thing? Such as:

MikeRalphson commented 5 years ago

I think a walkthrough of the process of creating an API description, then generating the documentation and hosting it will be valuable. The process of creating the actual functional API itself would probably be out of scope though. WDYT?

evenstensberg commented 5 years ago

Yes agree. As long as it shows something actionable I think we’re all in. The problem we’ve encountered with OpenAPI is the ability to style the page ourselves, and currently it is too much options out there to pick from. Optimally (request/wish) from the folks at nasa is that we’re auto generating the endpoints and/or through a CMS, but that is also out of scope

timothymcmackin commented 5 years ago

So you're asking for a kind of end-to-end tutorial that would cover:

  1. Getting an openapi spec from somewhere
  2. Installing widdershins and shins and their dependencies
  3. Customizing the widdershins transform
  4. Transforming openapi to markdown with widdershins
  5. Customizing the shins transform
  6. Transforming markdown to html with shins
  7. Publishing to github pages

Does that cover it?

evenstensberg commented 5 years ago

Yes! That would be great

KiwiTones commented 5 years ago

Hello,

This is indeed a very promising tool. And I agree that it needs a user guide to help people get started. Once I learn how to use it, I would be happy to try to help out with that.

I want to customise the table of contents. The examples of "Widdershins in the Wild" that are in the widdershins README.md show some really well organised TOCs (e.g. docs.split.cash). I have read the README and followed it. However, widdershins puts the tag name in the TOC; it does not usethe 'title' of the tagGroup in the widdershins environment file.

What would be really useful is a production-quality example of an OpenAPI spec and widdershins environment file with all the configuration settings to build a decent HTML page. Does one exist? (The PetStore example doesn't qualify as it's too simple.)

If this is not the appropriate place to post this question, then please delete it and indicate where I should post it.

Thanks and regards Tony

timothymcmackin commented 5 years ago

I can help with that. What's a good way to organize a large update like this? We'll have to:

(A) decide whether we're talking about a tutorial, an example, or task-based docs that cover things like how to customize the TOC. Tutorials tend to be harder to keep updated because if something changes early on, you might have to rewrite the tutorial entirely.

(B) break that plan into work items so no one person has to do it all.

What's a good way to decide on (A) and organize (B)?

MikeRalphson commented 5 years ago

I agree tutorials often solve the problem of the person writing the tutorial and can be a pain when they get out of date.

Task based documentation I feel we can take a stab at on the wiki, then bring it into the /docs folder and a github.io site later.

Some one-line comments here breaking down the perceived tasks, and people can volunteer by using the thumbs-up reaction?

timothymcmackin commented 5 years ago

If anyone would like to review it, I wrote a basic how-to to get us started in PR #252.

timothymcmackin commented 4 years ago

What's the next step after that basic how-to?