[MER-2446] Adjust styles for web and manpages (#176)

We are trying to use `docs/*` as both command manuals on the web as well as online manual distributed along with the binary. For that, we want to customize go-md2man output, especially the header part. This includes a fork of https://github.com/cpuguy83/go-md2man. This includes the title part and some whitespace handling modifications. Note that go-md2man is licensed under MIT license, which is the same as this repository. The file independently have a license header and a copyright notice with a SPDX header.
aviator-co · Jun 9, 2023 · 1b48199 · 1b48199
1 parent f987c51
commit 1b48199
Show file tree

Hide file tree

Showing 23 changed files with 603 additions and 135 deletions.
diff --git a/cmd/av/pr.go b/cmd/av/pr.go
@@ -5,13 +5,12 @@ import (
 )
 
 var prCmd = &cobra.Command{
-	Use: "pr",
+	Use:   "pr",
 	Short: "manage pull requests",
 }
 
 func init() {
 	prCmd.AddCommand(
 		prCreateCmd,
-
 	)
 }
diff --git a/docs/av-auth-status.1.md b/docs/av-auth-status.1.md
@@ -1,13 +1,15 @@
-# av-auth-status 1 "" av-cli "Aviator CLI User Manual"
+# av-auth-status
 
-# NAME
+## NAME
 
-av-auth-status - Show info about the logged in user.
+av-auth-status - Show info about the logged in user
 
-# SYNOPSIS
+## SYNOPSIS
 
-`av auth status`
+```synopsis
+av auth status
+```
 
-# DESCRIPTION
+## DESCRIPTION
 
 Shows information about the logged in user using their access token.
diff --git a/docs/av-commit-amend.1.md b/docs/av-commit-amend.1.md
@@ -1,21 +1,23 @@
-# av-commit-amend 1 "" av-cli "Aviator CLI User Manual"
+# av-commit-amend
 
-# NAME
+## NAME
 
 av-commit-amend - Amend a commit
 
-# SYNOPSIS
+## SYNOPSIS
 
-`av commit amend [-m <msg>| --message=<msg>] [--no-edit]`
+```synopsis
+av commit amend [-m <msg>| --message=<msg>] [--no-edit]
+```
 
-# DESCRIPTION
+## DESCRIPTION
 
 The tip of the current branch can be replaced by creating a new commit. During
 this process, the recorded tree is prepared as per usual. In cases where no
 other message is specified via the command-line option -m, the message from the
 original commit is utilized as the initial point rather than an empty message.
 
-# OPTIONS
+## OPTIONS
 
 `-m <msg>, --message=<msg>`
 : Use the given `<msg>` as the commit message.

diff --git a/docs/av-commit-create.1.md b/docs/av-commit-create.1.md
@@ -1,14 +1,16 @@
-# av-commit-create 1 "" av-cli "Aviator CLI User Manual"
+# av-commit-create
 
-# NAME
+## NAME
 
 av-commit-create - Record changes to the repository with commits
 
-# SYNOPSIS
+## SYNOPSIS
 
-`av commit create [-m <msg>| --message=<msg>] [-a | --all]`
+```synopsis
+av commit create [-m <msg>| --message=<msg>] [-a | --all]
+```
 
-# DESCRIPTION
+## DESCRIPTION
 
 Create a new commit containing the current contents of the index and the given
 log message describing the changes, then run **av stack sync** on all subsequent
@@ -17,7 +19,7 @@ child branches with the new commit.
 Previous to running **av commit-create**, add changes to the index via
 git-add(1) to incrementally "add" changes to the index.
 
-# OPTIONS
+## OPTIONS
 
 `-m <msg>, --message=<msg>`
 : Use the given `<msg>` as the commit message.

diff --git a/docs/av-commit-split.1.md b/docs/av-commit-split.1.md
@@ -1,10 +1,10 @@
-# av-commit-split 1 "" av-cli "Aviator CLI User Manual"
+# av-commit-split
 
-# NAME
+## NAME
 
-av-commit-split - Split a commit into multiple commits.
+av-commit-split - Split a commit into multiple commits
 
-# DESCRIPTION
+## DESCRIPTION
 
 Split the currently checked out commit into multiple commits. When invoked, it
 prompts you which diff chunks should be included in the first commit and asks

diff --git a/docs/av-fetch.1.md b/docs/av-fetch.1.md
@@ -1,13 +1,15 @@
-# av-pr-fetch 1 "" av-cli "Aviator CLI User Manual"
+# av-fetch
 
-# NAME
+## NAME
 
-av-fetch - Fetch latest repository state from github.
+av-fetch - Fetch latest repository state from GitHub
 
-# SYNOPSIS
+## SYNOPSIS
 
-`` av pr fetch``
+```synopsis
+av fetch
+```
 
-# DESCRIPTION
+## DESCRIPTION
 
-Fetch latest repository state from github.
+Fetch latest repository state from GitHub.
diff --git a/docs/av-init.1.md b/docs/av-init.1.md
@@ -1,10 +1,10 @@
-# av-init 1 "" av-cli "Aviator CLI User Manual"
+# av-init
 
-# NAME
+## NAME
 
-av-init - Initialize the repository for Aviator CLI.
+av-init - Initialize the repository for Aviator CLI
 
-# DESCRIPTION
+## DESCRIPTION
 
 Aviator CLI internally stores metadata in the repository. This command
 initializes the metadata storage for the repository.

diff --git a/docs/av-pr-create.1.md b/docs/av-pr-create.1.md
@@ -1,15 +1,17 @@
-# av-pr-create 1 "" av-cli "Aviator CLI User Manual"
+# av-pr-create
 
-# NAME
+## NAME
 
 av-pr-create - Create a pull request for the current branch
 
-# SYNOPSIS
+## SYNOPSIS
 
-`` av pr create [-t <title>| --title=<title>] [-b <body>| --body=<body>]
-    [--draft] [--edit] [--force] [--no-push] ``
+```synopsis
+av pr create [-t <title>| --title=<title>] [-b <body>| --body=<body>]
+    [--draft] [--edit] [--force] [--no-push]
+```
 
-# DESCRIPTION
+## DESCRIPTION
 
 Push the current branch and create a pull request if not exist. If the branch
 has a parent branch, you need to make a pull-request for the parent first. If
@@ -20,7 +22,7 @@ When there's already a pull-request, the command just pushes the branch to
 remote, and you are not asked to provide the title and the body. If you want to
 edit the pull-request description for the existing pull-request, use `--edit`.
 
-# OPTIONS
+## OPTIONS
 
 `-t <title>, --title=<title>`
 : Use the given `<title>` as the title for the pull request.
@@ -43,15 +45,17 @@ edit the pull-request description for the existing pull-request, use `--edit`.
 : Do not push the branch to the remote repository before creating the pull
   request.
 
-# EXAMPLES
+## EXAMPLES
 
 Create a pull request, specifying the body of the PR from standard input:
 
-    $ av pr create --title "Implement fancy feature" --body - <<EOF
-    > Implement my very fancy feature.
-    > Can you please review it?
-    > EOF
+```bash
+$ av pr create --title "Implement fancy feature" --body - <<EOF
+> Implement my very fancy feature.
+> Can you please review it?
+> EOF
+```
 
-# SEE ALSO
+## SEE ALSO
 
 `av-stack-submit`(1)
diff --git a/docs/av-stack-branch-commit.1.md b/docs/av-stack-branch-commit.1.md
@@ -1,21 +1,23 @@
-# av-stack-branch-commit 1 "" av-cli "Aviator CLI User Manual"
+# av-stack-branch-commit
 
-# NAME
+## NAME
 
 av-stack-branch-commit - Create a new branch in the stack with the staged changes
 
-# SYNOPSIS
+## SYNOPSIS
 
-`av stack branch-commit [-a | --all] [-b <branch_name> | --branch-name <branch_name>]
-[-m <msg>| --message=<msg>]`
+```synopsis
+av stack branch-commit [-a | --all] [-b <branch_name> | --branch-name <branch_name>]
+    [-m <msg>| --message=<msg>]`
+```
 
-# DESCRIPTION
+## DESCRIPTION
 
 Create a new branch that is stacked on the current branch and commit all
 staged changes with the specified arguments. One of `-b` or `-m` flags are
 required to create the branch.
 
-# OPTIONS
+## OPTIONS
 
 `-a, --all`
 : Automatically stage all modified/deleted files, (same as `git commit --all`)

diff --git a/docs/av-stack-branch.1.md b/docs/av-stack-branch.1.md
@@ -1,14 +1,16 @@
-# av-stack-branch 1 "" av-cli "Aviator CLI User Manual"
+# av-stack-branch
 
-# NAME
+## NAME
 
 av-stack-branch - Create or rename a branch in the stack
 
-# SYNOPSIS
+## SYNOPSIS
 
-`av stack branch [-m | --rename] [--parent <parent_branch>] <branch-name>`
+```synopsis
+av stack branch [-m | --rename] [--parent <parent_branch>] <branch-name>
+```
 
-# DESCRIPTION
+## DESCRIPTION
 
 Create a new branch that is stacked on the current branch by default
 
@@ -17,7 +19,7 @@ instead of creating a new branch. Branches should only be renamed
 with this command (not with git branch -m ...) because av needs to update
 internal tracking metadata that defines the order of branches within a stack.
 
-# OPTIONS
+## OPTIONS
 
 `--parent <parent_branch>`
 : Instead of creating a new branch from current branch, create it from

diff --git a/docs/av-stack-diff.1.md b/docs/av-stack-diff.1.md
@@ -1,13 +1,16 @@
-# av-stack-diff 1 "" av-cli "Aviator CLI User Manual"
+# av-stack-diff
 
-# NAME
+## NAME
 
-av-stack-diff - Show the diff between working tree and parent branch. 
+av-stack-diff - Show the diff between working tree and parent branch
 
-# SYNOPSIS
+## SYNOPSIS
 
-`av stack diff`
+```synopsis
+av stack diff
+```
 
-# DESCRIPTION
+## DESCRIPTION
 
-Generates the diff between the working tree and the parent branch (i.e., the diff between the current branch and the previous branch in the stack).
+Generates the diff between the working tree and the parent branch (i.e., the
+diff between the current branch and the previous branch in the stack).
diff --git a/docs/av-stack-next.1.md b/docs/av-stack-next.1.md
@@ -1,25 +1,29 @@
-# av-stack-next 1 "" av-cli "Aviator CLI User Manual"
+# av-stack-next
 
-# NAME
+## NAME
 
-av-stack-next - Checkout a later branch in the stack.
+av-stack-next - Checkout a later branch in the stack
 
-# SYNOPSIS
+## SYNOPSIS
 
-`av stack next [<n> | --last]`
+```synopsis
+av stack next [<n> | --last]
+```
 
-# DESCRIPTION
+## DESCRIPTION
 
-Checkout a later branch in the stack. Without any options, this will default to checking out the next branch in the stack.
+Checkout a later branch in the stack. Without any options, this will default to
+checking out the next branch in the stack.
 
-# OPTIONS
+## OPTIONS
 
 `<n>`
-: Checkout to the branch that is `<n>` branches after the current branch in the stack.
+: Checkout to the branch that is `<n>` branches after the current branch in the
+  stack.
 
 `--first`
 : Checkout to the last branch in the stack.
 
-# SEE ALSO
+## SEE ALSO
 
 `av-pr-prev`(1)
diff --git a/docs/av-stack-prev.1.md b/docs/av-stack-prev.1.md
@@ -1,25 +1,29 @@
-# av-stack-prev 1 "" av-cli "Aviator CLI User Manual"
+# av-stack-prev
 
-# NAME
+## NAME
 
-av-stack-prev - Checkout a previous branch in the stack.
+av-stack-prev - Checkout a previous branch in the stack
 
-# SYNOPSIS
+## SYNOPSIS
 
-`av stack prev [<n> | --first]`
+```synopsis
+av stack prev [<n> | --first]
+```
 
-# DESCRIPTION
+## DESCRIPTION
 
-Checkout a previous branch in the stack. Without any options, this will default to checking out the previous branch in the stack.
+Checkout a previous branch in the stack. Without any options, this will default
+to checking out the previous branch in the stack.
 
-# OPTIONS
+## OPTIONS
 
 `<n>`
-: Checkout to the branch that is `<n>` branches before the current branch in the stack.
+: Checkout to the branch that is `<n>` branches before the current branch in the
+  stack.
 
 `--first`
 : Checkout to the first branch in the stack.
 
-# SEE ALSO
+## SEE ALSO
 
 `av-pr-next`(1)