Cobra documentation overhaul #1254
Comments
|
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. |
|
#985:
|
|
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). |
|
@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.
Agree. Wikis are Projects changed from the settings. Packages and environments are disabled from the root.
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. |
|
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 👍 |
|
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: 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). |
|
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 ***@***.***> 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
<#1254 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AABKKZADNW7GJCAX4BHHDBDSLC733ANCNFSM4SQZQBFA>
.
|
|
This issue is being marked as stale due to a long period of inactivity |
|
Team to investigate github page static site hosting. |
|
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 ***@***.***> 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
<#1254 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AABKKZHGAKV6STNRSLT4KVTSVPMPJANCNFSM4SQZQBFA>
.
|
Demo available: #1245. Just need to select a theme that maintainers like. |
|
This issue is being marked as stale due to a long period of inactivity |
|
Closing this as stale with the resolution that the https://cobra.dev website has been made available by @spf13 |
I've noticed that
README.mdhas become a bit of a dumping ground for documenting any and all of cobra's APIs. For example: #1135Instead, 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
*.mdfiles with more organization.Any suggestions from the community?
The text was updated successfully, but these errors were encountered: