docs: Centralize documentation

[johnaoss]

As the Wiki feature is enabled on this repo, I suggest that we move the docs to a central location.

Where

Ideally this could be the Wiki. We could copy over all of the .md files into there with minimal effort. As a temporary measure, we can keep both the .md files in-repo, and just mirror them in the Wiki as separate pages, with the end goal of removing from the repo entirely.

If the Wiki is deemed as an improper place to put this documentation, I then suggest something like a /docs folder. This is seemingly common in several other Go projects, and would allow the documentation to still be kept locally after cloning the repo. The only downside for this is that there currently exists a /doc folder, which could be confusing to some.

Why

This would have the benefit of allowing a place for more in-depth tutorials for people looking to adapt cobra for their own use cases. This could also contain a sort of FAQ for common issues.
As an additional benefit, this could potentially provide a single place to address the concerns @umarcor outlined in issue #959.

The main reason I'm asking for something like this is that there seem to be a couple open issues about documentation that are unresolved. I am planning to contribute fixes to those issues, I'm just unsure of where to place said docs. I personally think the Wiki could be a good place for me to start, unless there is some other method that is preferred.

[umarcor]

First off, I'm all in with having proper documentation. Thanks for opening this issue!

Ideally this could be the Wiki. We could copy over all of the .md files into there with minimal effort.

GitHub wikis are, in fact, git repositories with markdown files. Hence, you can clone either [email protected]:user/repo.wiki.git or https://github.com/user/repo.wiki.git, edit files locally, commit the changes and push. The website is just a frontend that allows to edit sources without using git. As a result, it is possible to add the wiki repo as a submodule of the main repository, so that it is distributed with the sources. However, there are some caveats:

• There is no support for handling PRs to wikis. Therefore, all the contributions to the wiki through git need to be explicitly cherry-picked by maintainers using CLI.
• AFAIK, there is no support for visualizing different branches of the wiki. It is possible to have them in the repo, but only master is shown on the website. This makes it difficult to review contributions, unless contributors do all their modifications in master.
• As a result, it is difficult for multiple users to work on parallel modifications that affect the same files/pages. The traditional approach in wikis is that one of the editors will overwrite the other, so they must communicate beforehand. There are workflows to avoid content being lost, but it is still not as polished as contribution in regular git repos.

IMHO, the GitHub wiki frontend provides few advantages for open collaborative development. It is good for two contexts:

• When a reduced number of maintainers (contributors with write access) are the only ones that can edit it directly.
• When it is open for anyone to edit, but it is considered a playground/draft.

I'm afraid that those contexts do not fit with the current status of cobra. We want many different users with various levels of access rights to suggest modifications in parallel. And we want maintainers to be able to easily compare/view multiple branches/versions.

As a temporary measure, we can keep both the .md files in-repo, and just mirror them in the Wiki as separate pages, with the end goal of removing from the repo entirely.

Because of the reasons exposed above, I think that this should not be a temporary measure, but permanent. Sources of the documentation can be located as a subdir of the main repo or as a sibling repo, but anyway, we should ignore the wiki frontend as an editor (for now). Personally, I think that keeping the docs in the same repo is better in this project.

Of course, it is possible to create spf13/cobra-wiki as the canonical location of the docs. Then, that repo can be both added as a submodule to spf13/cobra and mirrored to spf13/cobra.wiki. This would be preferred if we wanted to support edition through the wiki frontend, apart from contribution through the regular PR workflow. Nonetheless, as said, I think that this is looking for problems.

---

So, assuming that we agree on gathering all the docs as markdown sources in a subdir of the main repo, we can discuss different approaches to view them:

• The most obvious is using a local editor/IDE (say VSCode), or the regular features of the GitHub site.
• Apart from that, it is possible to use a GitHub Action to periodically mirror the subdir to spf13/cobra.wiki. The main advantage I can think about is that the wiki provides a sidebar which can be helpful. Apart from that, the wiki supports wiki-alike links and the regular frontend does not. Anyway, I think that very few users would really use the wiki as a view-only resource.
• cobra was born precisely to support hugo, which is a static site generator for markdown sources.
  • Hence, it seems natural to add a configuration file and use a GitHub Action in order to release the docs as a website (spf13.github.io/cobra). The default GITHUB_TOKEN allows to push to branch gh-pages, so it can be handled as a regular PR.
  • It is possible to link back from each page to the source in the repo, so that users willing to contribute can quickly edit them.

Unfortunately, hugo is more of a blog site or personal site generator than a documentation site generator: https://discourse.gohugo.io/t/hugo-as-a-documentation-tool/112. This raises some limitations. Of course, hugo is being enhanced, and it could be possible to overcome some of the limitations through curated templates. However, I feel that none of the available themes is there yet: https://themes.gohugo.io/tags/documentation/ . 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.

Just as a curiosity, in 1138-4EB/elide the wiki is used to edit part of the documentation. Then, in a CI job, the repo of the wiki is cloned, and sources are modified in order to include them in a hugo site. So, this wiki is viewed as 1138-4eb.github.io/elide/wiki/Menu. Note that there is a dropdown menu in each article that links to 'Source', 'Edit', 'History' and 'Comment'. However, it relies on a shell script and regular expressions (https://github.com/1138-4EB/elide/blob/master/site/travis-deploy-pages2master.sh#L7-L42), which is prone to fail.

• Alternative static site generators are Jekyll (Ruby, for markdown), Sphinx (Python, for reStructuredText, although markdown is supported too), GitBook (JS, for markdown), asciidoc, mdbook, etc. However, I don't think any of these provides any signifficant advantage for cobra, compared to hugo.

My first bet would be to try hugo and gohugoio/gohugoioTheme. However, I don't know if gohugoioTheme is expected to be used by any project other than hugo. @bep?

---

If the Wiki is deemed as an improper place to put this documentation, I then suggest something like a /docs folder. This is seemingly common in several other Go projects, and would allow the documentation to still be kept locally after cloning the repo. The only downside for this is that there currently exists a /doc folder, which could be confusing to some.

The documentation can be added to a subdir named site or .doc. Alternatively, the current doc subdir can be renamed to gendoc.

This would have the benefit of allowing a place for more in-depth tutorials for people looking to adapt cobra for their own use cases. This could also contain a sort of FAQ for common issues.
As an additional benefit, this could potentially provide a single place to address the concerns @umarcor outlined in issue #959.

Related issues/discussions:

• Docs needed: how best to handle errors in Run #914
• Document howto generate completions #932
• Document a best practice for testing a cobra app #770
• #973

[jharshman]

There are improvements to be made in documentation. But I think it is a better idea to keep the docs co-located with the code as it is today.

[umarcor]

@jharshman, I think that this issue should be kept open to track improvements to centralize the documentation; even if sources are to be located in the same repo.