Cobra documentation overhaul

[jpmcb]

I've noticed that README.md has become a bit of a dumping ground for documenting any and all of cobra's APIs. For example: https://github.com/spf13/cobra/pull/1135

Instead, I would like to see a better strategy around documenting the public APIs that Cobra provides. My suggestion would be to have a folder of *.md files with more organization.

Any suggestions from the community?

[eparis]

I agree, it's a dumping ground (and probably about 99% my fault.) Don't most projects do this with better godocs? I'd love to see the readme almost entirely gone with godoc style documentation and examples.

[umarcor]

985:

It is also unfortunate that AFAIK godoc does not support any kind of templating. As a result, it is not easy (even possible?) to integrate godoc's knowledge into a custom hugo site.

1244:

Furthermore, using gohugo for building a documentation site from markdown sources was discussed in #985.

1245:

In this PR, a GitHub Actions workflow is added for building a web site with Hugo and deploying it to GitHub Pages (branch gh-pages).

Proposed README: https://github.com/umarcor/cobra/blob/ci-site/README.md

[lukasmalkmus]

Recently had to write some documentation for a private project. I ended up using MkDocs + GitHub Pages. It is super straight forward and I think one of the best options for OSS projects. As much as I love Hugo, MkDocs is just so awesome for documentation, also the deployment is super painless with GitHub Actions.

We should also clean up the README and disable the Wikis tab (as well as unused tabs and sections like Projects, Packages and Environments).

GoDoc is awesome but lacks more advanced features IMHO. We can barley utilize it for proper application code examples, etc. Still good to document the library (which it does).

[umarcor]

@lukasmalkmus, in fact, Hugo, MkDocs, Jekyll, Sphinx, asciidoc, etc. are all the same from a usage and deployment point of view. All of them can be executed with GitHub Actions (or any other CI service) and painlessly pushed to GitHub Pages. See https://dbhi.github.io/mdpaper (work in progress). I believe that the main issue is finding a template that fits, regardless of the static generator.

OTOH, cobra was created for hugo. That's why it feels natural to use it instead of other alternatives. Contributors to cobra are expected to know golang, so they can better edit and extend the templates. Other alternatives require Python or Ruby.

We should also clean up the README and disable the Wikis tab (as well as unused tabs and sections like Projects, Packages and Environments).

Agree. Wikis are Projects changed from the settings. Packages and environments are disabled from the root.

GoDoc is awesome but lacks more advanced features IMHO. We can barley utilize it for proper application code examples, etc. Still good to document the library (which it does).

Agree. At the same time, I believe there should be many references from the documentation site to the godoc pages.

A shortcut for making this easier is the kind of customisations that might be desirable in the static site generator.

[lukasmalkmus]

Good points. Personally I think MkDocs + Material is a very good choice and feature rich, even for "code-centric" documentation. GoReleaser uses it: https://goreleaser.com We could introduce a small template that links code blocks nicely to GoDoc using a proper button.

But I just noticed you have an open PR, so this might be a good first step 👍

[umarcor]

Personally, I am not convinced about Material themes. However, I don't have a better proposal; hence, that's a perfectly valid solution.

My main point regarding layout is that Cobra would greatly benefit from a two-column + sidebar layout on regular desktop screens. That's because most of the docs are commented code examples. Unfortunately, neither MkDocs nor asciidoctor allow it:

• https://goreleaser.com/quick-start/
• https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

The DocuAPI template is precisely meant for that: https://umarcor.github.io/cobra/. However, as you see, some tweaking is required, because code blocks are not collapsible, and some of the examples are really long. Moreover, although gohugo supports complex hierarchies and taxonomies, DocuAPI places all the content in a single page. Apart from that DocuAPI is not a regular theme, as it requires JS and go dependencies.

This is to say that my PR is for discussing moving all the markdown sources to an specific subdir, reworking the README, adding shields, using CI for building the site, etc. I don't think DocuAPI is the best solution, and I don't have any strong feeling for using hugo. If it needs to be MkDocs + Material, let it be 😄 . Yet, note that @spf13 created https://cobra.dev/ already (even though sources are not available yet AFAIAA).

[spf13]

I personally find this style of docs very confusing. I'll work on opening up the cobra.dev code next week as time permits.

On Fri, Oct 16, 2020 at 6:07 PM umarcor notifications@github.com wrote:

Personally, I am not convinced about Material themes. However, I don't have a better proposal; hence, that's a perfectly valid solution.

My main point regarding layout is that Cobra would greatly benefit from a two-column + sidebar layout on regular desktop screens. That's because most of the docs are commented code examples. Unfortunately, neither MkDocs nor asciidoctor allow it:

• https://goreleaser.com/quick-start/
• https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

The DocuAPI template is precisely meant for that: https://umarcor.github.io/cobra/. However, as you see, some tweaking is required, because code blocks are not collapsible, and some of the examples are really long. Moreover, although gohugo supports complex hierarchies and taxonomies, DocuAPI places all the content in a single page. Apart from that DocuAPI is not a regular theme, as it requires JS and go dependencies.

This is to say that my PR is for discussing moving all the markdown sources to an specific subdir, reworking the README, adding shields, using CI for building the site, etc. I don't think DocuAPI is the best solution, and I don't have any strong feeling for using hugo. If it needs to be MkDocs + Material, let it be 😄 . Yet, note that @spf13 https://github.com/spf13 created https://cobra.dev/ already (even though sources are not available yet AFAIAA).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/spf13/cobra/issues/1254#issuecomment-710674796, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABKKZADNW7GJCAX4BHHDBDSLC733ANCNFSM4SQZQBFA .

[github-actions[bot]]

This issue is being marked as stale due to a long period of inactivity

[jharshman]

Team to investigate github page static site hosting.

[spf13]

Sorry for the staleness on this. I'll open the source up next week. I'm off work so I'll make time for it.

On Fri, Dec 18, 2020 at 5:53 PM Joshua Harshman notifications@github.com wrote:

Team to investigate github page static site hosting.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/spf13/cobra/issues/1254#issuecomment-748357697, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABKKZHGAKV6STNRSLT4KVTSVPMPJANCNFSM4SQZQBFA .

[umarcor]

Team to investigate github page static site hosting.

Demo available: #1245. Just need to select a theme that maintainers like.

[github-actions[bot]]

This issue is being marked as stale due to a long period of inactivity

[jharshman]

Closing this as stale with the resolution that the https://cobra.dev website has been made available by @spf13