deploy-cobra-mkdocs-versioned-poetry.md

"Deploy Website" workflow (Cobra, versioned, MkDocs, Poetry)

Generate a command line reference for projects using the Cobra Go module and deploy a versioned MkDocs-based static website to GitHub Pages.

This uses Cobra's built-in Markdown documentation generation capability:
https://github.com/spf13/cobra/blob/main/site/content/docgen/md.md

Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important for the reader to be able to access the documentation for the specific version of the project they are using. The system provides a easy access to a website version for the documentation content at:

• The tip of the default branch ("dev")
• The latest release ("latest")
• Each minor version series (e.g., "1.2")

The website version is selectable via a menu on the website as well as the URL of each documentation page.

Installation

Workflow

Install the deploy-cobra-mkdocs-versioned-poetry.yml GitHub Actions workflow to .github/workflows/

Assets

• Base assets - See the "Deploy Website" workflow (versioned, MkDocs, Poetry) documentation
• Taskfile.yml - documentation generation tasks.
  • Install to: repository root (or merge into the existing Taskfile.yml).
• Taskfile.yml - documentation formatting task.
  • Merge into Taskfile.yml
• docsgen - command line reference generator.
  • Install to: docsgen/

Dependencies

See the "Deploy Website" workflow (versioned, MkDocs, Poetry) documentation for the instructions to install the dependencies

Configuration

Workflow

Configure the version of Go used for development of the project in the env.GO_VERSION field of deploy-cobra-mkdocs-versioned-poetry.yml.

Taskfile

Set the PROJECT_NAME variable to the project name.

If there are any additional documentation generation tasks, add them to the docs:generate umbrella task.

docsgen

• go.mod - replace MODULE_NAME with the project's module name.
• main.go
  • replace CLI_PACKAGE_NAME with the project's Cobra CLI package name
  • replace cli.NewCommand() with the project's Cobra CLI package function for command root generation

Run the following command from the docsgen/ folder:

go mod tidy

Commit the resulting docsgen/go.sum file to the repository.

Configure base assets

See the "Deploy Website" workflow (versioned, MkDocs, Poetry) documentation.

Define "dev" source branch

The system is configured for the repository branch used as the source for the "dev" website version having the name main. If the project's development branch has another name, then configure it:

• on.push.branches[0] in deploy-cobra-mkdocs-versioned-poetry.yml
• DEV_BRANCHES in docs/siteversion/siteversion.py

Configure .gitignore

Add the following to .gitignore:

/docsgen/<application executable>
/docsgen/<application executable>.exe
/docs/commands/*.md

(where "<application executable>" is the filename of the application's executable, as defined in the Taskfile PROJECT_NAME variable.

Setup

1. Checkout the branch of the repository that contains the documentation source files for the "dev" version of the website (e.g., main).
2. Run the following command:

   task docs:generate
   

3. Follow the remaining setup steps from the "Deploy Website" workflow (versioned, MkDocs, Poetry) documentation.

Documentation

Readme badge

Markdown badge:

[![Deploy Website status](https://github.com/TODO_REPO_OWNER/TODO_REPO_NAME/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg)](https://github.com/TODO_REPO_OWNER/TODO_REPO_NAME/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml)

Replace the TODO_REPO_OWNER and TODO_REPO_NAME placeholders in the URLs with the final repository owner and name (example).

---

Asciidoc badge:

image:https://github.com/{repository-owner}/{repository-name}/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg["Deploy Website status", link="https://github.com/{repository-owner}/{repository-name}/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml"]

Define the {repository-owner} and {repository-name} attributes and use them throughout the readme (example).

Development Guide

See the "Deploy Website" workflow (MkDocs, Poetry) documentation

Website versioning

See the "Deploy Website" workflow (versioned, MkDocs, Poetry) documentation for an explanation of how the versioning works.

Commit message

Add CI workflow to deploy a versioned MkDocs-based website to GitHub Pages

On every push to the repository's default branch or release branch, generate a command line reference and deploy the
repository's MkDocs-based static website to GitHub Pages.

Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important
for the reader to be able to access the documentation for the specific version of the project they are using.

The documentation system provides access to:

- The tip of the default branch ("dev")
- The latest release ("latest")
- Each minor version series (e.g., "1.2")

The website version is selectable via a menu on the website as well as the URL of each documentation page.

PR message

On every push to the repository's default branch, generate a command line reference and deploy the repository's [MkDocs](https://www.mkdocs.org/)-based static website to [GitHub Pages](https://pages.github.com/).

Documentation content will sometimes apply only to a specific version of the project. For this reason, it's important
for the reader to be able to access the documentation for the specific version of the project they are using.

With the help of [mike](https://github.com/jimporter/mike), the documentation system provides access to:

- The tip of the default branch ("dev")
- The latest release ("latest")
- Each minor version series (e.g., "1.2")

The website version is selectable via a menu on the website as well as the URL of each documentation page.