Thanos: docs: documentation generator for a pretty website

[adrien-f]

👋 Yello !

As discussed on Slack, I propose to open this issue so we can track the progress on this.

The main goal would be to host a little website prettifying what's in docs/ so we can also have example cluster architectures, a central place to link to talks/testimonials/experiences/...

A few proposals:

• DIY: Build ourselves tooling to generate the documentation with an HTML template
• Docusaurus: seems to be the latest docs generator trending
• Hugo
• Jekyll
• Gitbook

And more resources: https://github.com/PharkMillups/beautiful-docs, I'd love to see what our monitoring friends use.

What kind of features to look for ? Here's a starting list to get the conversation started:

• Documentation versionning (always pointing to master, but keep docs for v0.0.2 available for example)
• Markdown based
• Easy to integrate with Github and CircleCI
• Easy to add/edit content, add links, embed videos/slides
• KISS
• ...

[adrien-f]

Played with Docusaurus this afternoon:

[domgreen]

Few things that I would want from this:

1. Use main thanos repo to keep overhead to minimum
2. Automatic generation of site via CI
3. Support versions
4. Support markdown for generation of proposal docs, flags, diagrams etc.

[bwplotka]

Thanks for starting this up. :heart:

Easy hosting option would be nice as well (:

[bwplotka]

Is there any easy option to see docs from previous releases from the quick PoC you did (https://github.com/improbable-eng/thanos/issues/757#issuecomment-456890501)? @adrien-f

[adrien-f]

It looks like it's supported: https://docusaurus.io/docs/en/versioning

Haven't tried it though

[FUSAKLA]

Would be great to have diagrams versioned and generated something like http://plantuml.com/
(looks like docusaurus has plugin for this https://github.com/webgears/remarkable-plantuml)

But I saw diagrams done using ASCII so maybe that's enough?

[domgreen]

I think having the site itself hosted and served from GitHub pages would be a massive win. I really like the look of Docusourous 🦖

[jojohappy]

Agree with @domgreen . But Docusourous + Github pages will be also a good option.

[bwplotka]

For diagrams we have either Ascii or just direct link to Google Drawings.. (: Which is cool because editable easily.

[domgreen]

@adrien-f How much of the *.js code was auto-generated on your test branch, compared to handwritten (react scares me 👹)?

As a pure golang alternative It would be good to see a compare and contrast with Hugo as it was another project the Prom maintainers were also looking at.

[bwplotka]

Yup, some PoC in Hugo would be nice, as it gives similar advantages and has large user group... unless it takes too much time to set it up it in short time.

[domgreen]

I would hope that 90% of my time would be spent editing markdown for the site and letting CI automagically generate and publish the site.

[adrien-f]

I've deployed an example with Docusaurus on my fork : https://adrien-f.github.io/thanos/

@domgreen: the majority of the js was already generated, I just wrote some content and a few lines of CSS. Though JSX is mostly html with a few niceties, no need to get into complex React adventures :smile: !

I'll try something with Hugo as well.

[bwplotka]

Kubernetes in May 2018 moved from Jekyll to Hugo. Wonder if they have something rdy to use... (ref: https://kubernetes.slack.com/archives/C9T0QMNG4/p1525964738000177)

[adrien-f]

Hi everyone :wave:

Updated my fork with a test run of Hugo: https://adrien-f.github.io/thanos/

If you want to see the diff: https://github.com/improbable-eng/thanos/compare/master...adrien-f:feature/docs-hugo?expand=1

My thoughts:

• Did not found a theme to my liking so went with a basic Bootstrap one from scratch
• Might be a lot of maintenance in the future
• Still not a web designer :smile:
• Not sure how to do versioning with it
• Full control over anything, you can add custom HTML, markdown tags, videos, probably some AsciiSchema or Mermaid
• Structure is a bit hard to work with at first (you can see I did a symlink but that is not needed)
• Haven't worked on the responsive mobile view

Let me know what you think @domgreen @bwplotka !

[bwplotka]

@domgreen Hugo looks really good enough to me. We had offline demo in Brussels with @adrien-f and it sounds like something simple and flexible for future :+1:

Thanks for good work @adrien-f .. now we need to decid which one we agree on and how we can start using it. (: I will start PR from your commit @adrien-f for hugo.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.