Problem statement

Our documentation site, https://goswagger.io is powered by the venerable gitbook .
Here are a few impediments with go-swagger documententation:

• The look and feel hasn't improved in years.
• The build is not automated
• There isn't much control over the layout, menus, etc.
• There is no incentive to improve docs (e.g. direct editiing pages, with faster CI path...)
• The documentation structure has grown and is now rather confusing
• As a consequence, content & accuracy degrade over time

Proposal

I've been working on a prototype to produce a revamped documentation site.

You may see it in action on my active fork (still some rough edges, as there is some WIP on content): https://fredbi.github.io/go-swagger/

What's on the table?

• doc site built with hugo, using theme "hugo-book"

Why HUGO?
The contemplated alternative is Jeckyll, which comes with a better integration with github.
At this point, the choice is: "going full github, tick all the boxes" vs "using a widespread alterative, with more control over the published content".

Why hugo-book?
After some time researching and experimenting various templates, this one was standing out (IMHO)
as the one with easiest configuration and closest rendering to what I wanted (with an overall organization
similar to the one produced by gitbook). It worked almost out of the box, with little customization that I could
add later on (e.g. tabs, collapsible sections, etc).

Lately I've also tried "docsy" (a rich template by google/netlify), but I found it a bit complex.
It also came with strong opinions about how to document a project. Although these ideas are good,
they needed an even deeper restructuing of our markdown material.

• markdown content now use "frontmatter" headers

Tried to add minimal frontmatter, with maximum reliance on the theme.

• doc layout changed to accomodate how hugo builds a site hierarchy

• used a few "shortcodes" from the theme for a more compelling UI (e.g. tabs, collapsible sections, ...)

• link to edit the page (creates a new PR with the page)

• doc site built from github actions at every push to master (see https://github.com/fredbi/go-swagger/blob/master/.github/workflows/update-doc.yaml)

• github pages are deployed using the "gh-pages" artifact.

What's still missing?

There is still quite some work ahead, though.

• a complete review of the content: we need to recap, check for accuracy, provide more examples, etc. _ that would be for later_
• publish docs for multiple versions (I've built a small prototype for that part as well, but it's still incomplete)
• not sure how the custom domain on top of github.com/go-swagger.github.io would behave with the new artifact-based deployment
• a separate CI fast lane for doc-only PRs (again, prototype to illustrate this here: ci: experiments with github actions fredbi/analysis#1)

@casualjim @youyuanwu how about that?