Docs (#270)

* Basic CLI Docs generation

Author: frjcomp

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Deploy CLI Docs
+
+on:
+  push:
+    branches:
+      - main
+jobs:
+  build-and-deploy-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+
+      - name: Generate Docs with Go
+        working-directory: src/pipeleak
+        run: go run main.go docs
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.x'
+
+      - name: Install MkDocs
+        run: pip install mkdocs mkdocs-material
+
+      - name: Build Docs
+        run: mkdocs build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: 'site/'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,6 @@
 rules.yml
 *.log
-dist
+dist
+renovate-enum-out
+cli-docs
+site

mkdocs.yml

@@ -0,0 +1,9 @@
+site_name: Pipeleak CLI Docs
+docs_dir: src/pipeleak/cli-docs
+site_dir: site
+theme:
+  name: material
+  palette:
+    scheme: slate
+extra:
+  highlightjs: true

readme.md

@@ -27,6 +27,8 @@ Run the following command to scan your e.g. GitLab instance:
 pipeleak gl scan --token glpat-xxxxxxxxxxx --gitlab https://gitlab.com
 ```
 
+More detailed command documentation can be found [here](https://compasssecurity.github.io/pipeleak/pipeleak/).
+
 ### Scanning Artifacts
 
 In addition to logs, Pipeleak can also scan artifacts generated by your pipelines.

src/pipeleak/cmd/docs/docs.go

@@ -0,0 +1,32 @@
+package docs
+
+import (
+	"os"
+
+	"github.com/rs/zerolog/log"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+func NewDocsCmd(root *cobra.Command) *cobra.Command {
+	return &cobra.Command{
+		Use:   "docs",
+		Short: "Generate CLI documentation",
+		Long:  "Generate Markdown documentation for all commands in this CLI application.",
+		Run: func(cmd *cobra.Command, args []string) {
+			outputDir := "./cli-docs"
+
+			if err := os.MkdirAll(outputDir, os.ModePerm); err != nil {
+				log.Fatal().Err(err).Msg("Failed to create cli-docs directory")
+			}
+
+			err := doc.GenMarkdownTree(root, outputDir)
+			if err != nil {
+				log.Fatal().Err(err).Msg("Failed to generate cli docs")
+			}
+
+			log.Info().Str("folder", outputDir).Msg("Docs successfully generated")
+		},
+	}
+}

src/pipeleak/cmd/root.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/CompassSecurity/pipeleak/cmd/bitbucket"
 	"github.com/CompassSecurity/pipeleak/cmd/devops"
+	"github.com/CompassSecurity/pipeleak/cmd/docs"
 	"github.com/CompassSecurity/pipeleak/cmd/github"
 	"github.com/CompassSecurity/pipeleak/cmd/gitlab"
 	"github.com/rs/zerolog"
@@ -39,6 +40,7 @@ func init() {
 	rootCmd.AddCommand(gitlab.NewGitLabRootCmd())
 	rootCmd.AddCommand(bitbucket.NewBitBucketRootCmd())
 	rootCmd.AddCommand(devops.NewAzureDevOpsRootCmd())
+	rootCmd.AddCommand(docs.NewDocsCmd(rootCmd))
 	rootCmd.PersistentFlags().BoolVarP(&JsonLogoutput, "json", "", false, "Use JSON as log output format")
 	rootCmd.PersistentFlags().BoolVarP(&LogColor, "coloredLog", "", true, "Output the human-readable log in color")
 	rootCmd.PersistentFlags().StringVarP(&LogFile, "logfile", "l", "", "Log output to a file")

src/pipeleak/go.mod

@@ -60,6 +60,7 @@ require (
 	github.com/couchbase/gocbcoreps v0.1.3 // indirect
 	github.com/couchbase/goprotostellar v1.0.2 // indirect
 	github.com/couchbaselabs/gocbconnstr/v2 v2.0.0-20240607131231-fb385523de28 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect
 	github.com/envoyproxy/protoc-gen-validate v1.2.1 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
@@ -110,6 +111,7 @@ require (
 	github.com/prometheus/common v0.55.0 // indirect
 	github.com/prometheus/procfs v0.15.1 // indirect
 	github.com/rabbitmq/amqp091-go v1.10.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/tailscale/depaware v0.0.0-20250112153213-b748de04d81b // indirect
 	github.com/tetratelabs/wazero v1.9.0 // indirect
 	github.com/tidwall/match v1.1.1 // indirect

src/pipeleak/go.sum

@@ -152,6 +152,7 @@ github.com/couchbaselabs/gocbconnstr/v2 v2.0.0-20240607131231-fb385523de28 h1:lh
 github.com/couchbaselabs/gocbconnstr/v2 v2.0.0-20240607131231-fb385523de28/go.mod h1:o7T431UOfFVHDNvMBUmUxpHnhivwv7BziUao/nMl81E=
 github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
 github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
+github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -442,6 +443,7 @@ github.com/rogpeppe/go-internal v1.13.1/go.mod h1:uMEvuHeurkdAXX61udpOXGD/AzZDWN
 github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
 github.com/rs/zerolog v1.34.0 h1:k43nTLIwcTVQAncfCw4KZ2VY6ukYoZaBPNOE8txlOeY=
 github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd/go.mod h1:hPqNNc0+uJM6H+SuU8sEs5K5IQeKccPqeSjfgcKGgPk=
 github.com/rxwycdh/rxhash v0.0.0-20230131062142-10b7a38b400d h1:pVClFYVn4nLE5D8YiihMwOznjoTuM8vA/6Rk6Jrkfe0=