Docs: User Guides

[evenstensberg]

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]

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

[MikeRalphson]

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]

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

• How to create a petstore api and deploy it to gh pages with widdershins?

[MikeRalphson]

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]

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]

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]

Yes! That would be great

[KiwiTones]

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]

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]

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]

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

[timothymcmackin]

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

• Deployment to gh-pages
• Customization of TOC (pretty complex topic; I do this by editing the HTML in the Shins transform)
• End-to-end example project (widdershins + shins)
• Better examples of what the Widdershins params do with some before-after examples
• Something else?