✨ Autogenerate manpages and markdown docs

Justfile

@@ -11,6 +11,10 @@ install:
 	cp ortfodb ~/.local/bin/ortfodb
 	chmod +x ~/.local/bin/ortfodb
 
+docs:
+	mkdir -p docs manpages
+	./ortfodb makedocs
+
 render-demo-gif:
 	#!/usr/bin/env bash
 	set -euxo pipefail
@@ -22,6 +26,7 @@ render-demo-gif:
 prepare-release $VERSION:
 	./tools/update_meta_go.py $VERSION
 	just build
+	just docs
 	./tools/generate_schemas.py
 	./tools/build_readme.py
 	just build-packages $VERSION

cmd/main.go

@@ -8,6 +8,7 @@ import (
 	"github.com/muesli/reflow/indent"
 	ortfodb "github.com/ortfo/db"
 	"github.com/spf13/cobra"
+	cobradoc "github.com/spf13/cobra/doc"
 )
 
 // rootCmd represents the base command when called without any subcommands
@@ -31,6 +32,16 @@ func init() {
 
 // Execute adds all child commands to the root command and sets flags appropriately.
 func main() {
+	if len(os.Args) == 2 && os.Args[1] == "makedocs" {
+		cobradoc.GenMarkdownTree(rootCmd, "./docs")
+		cobradoc.GenManTree(rootCmd, &cobradoc.GenManHeader{
+			Title:   "ORTFODB",
+			Section: "1",
+			Source:  "https://ortfo.org/db",
+			Manual:  "ortfo/db Manual",
+		}, "./manpages")
+		os.Exit(0)
+	}
 	err := rootCmd.Execute()
 	if err != nil {
 		os.Exit(1)

docs/README.md

@@ -0,0 +1,3 @@
+# Documentation of ortfo/db
+
+See <https://ortfo.org/db> for the complete documentation.

docs/ortfodb.md

@@ -0,0 +1,32 @@
+## ortfodb
+
+Manage your portfolio's database
+
+### Synopsis
+
+Manage your portfolio's database — See https://github.com/ortfo/db for more information.
+
+### Examples
+
+```
+  $ ortfodb --config .ortfodb.yaml build database.json
+  $ ortfodb add my-project
+```
+
+### Options
+
+```
+  -c, --config string   config file path (default "ortfodb.yaml")
+  -h, --help            help for ortfodb
+      --scattered       Operate in scattered mode. In scattered mode, the description.md files are searched inside `.ortfo' folders in every folder of the database directory, instead of directly in the database directory's folders. See https://github.com/ortfo/
+```
+
+### SEE ALSO
+
+* [ortfodb add](ortfodb_add.md)	 - Add a new project to your portfolio
+* [ortfodb build](ortfodb_build.md)	 - Build the database
+* [ortfodb exporters](ortfodb_exporters.md)	 - Commands related to ortfo/db exporters
+* [ortfodb replicate](ortfodb_replicate.md)	 - Replicate a database directory from a built database file.
+* [ortfodb schemas](ortfodb_schemas.md)	 - Output JSON schemas for ortfodb's various resources
+
+###### Auto generated by spf13/cobra on 15-Apr-2024

docs/ortfodb_add.md

@@ -0,0 +1,31 @@
+## ortfodb add
+
+Add a new project to your portfolio
+
+### Synopsis
+
+Create a new project in the appropriate folder. ID is the work's slug.
+
+```
+ortfodb add <id> [flags]
+```
+
+### Options
+
+```
+  -h, --help        help for add
+      --overwrite   Overwrite the description.md file if it already exists
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   config file path (default "ortfodb.yaml")
+      --scattered       Operate in scattered mode. In scattered mode, the description.md files are searched inside `.ortfo' folders in every folder of the database directory, instead of directly in the database directory's folders. See https://github.com/ortfo/
+```
+
+### SEE ALSO
+
+* [ortfodb](ortfodb.md)	 - Manage your portfolio's database
+
+###### Auto generated by spf13/cobra on 15-Apr-2024

docs/ortfodb_build.md

@@ -0,0 +1,41 @@
+## ortfodb build
+
+Build the database
+
+### Synopsis
+
+Scan in the projects directory for folders with description.md files (and potential media files) and compile the whole database into a JSON file at <to-filepath>.
+
+If <to-filepath> is "-", the output will be written to stdout.
+
+If [include-works] is provided, only works that match the pattern will be included in the database.
+
+
+```
+ortfodb build <to-filepath> [include-works] [flags]
+```
+
+### Options
+
+```
+  -e, --exporters stringArray   Exporters to enable. If not provided, all the exporters configured in the configuration file will be enabled.
+  -h, --help                    help for build
+  -m, --minified                Output a minifed JSON file
+      --no-cache                Disable usage of previous database build as cache for this build (used for media analysis among other things).
+  -q, --silent                  Do not write to stdout
+      --workers int             Use <count> workers to build the database. Defaults to the number of CPU cores. (default 12)
+      --write-progress string   Write progress information to a file. See https://pkg.go.dev/github.com/ortfo/db#ProgressInfoEvent for more information.
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   config file path (default "ortfodb.yaml")
+      --scattered       Operate in scattered mode. In scattered mode, the description.md files are searched inside `.ortfo' folders in every folder of the database directory, instead of directly in the database directory's folders. See https://github.com/ortfo/
+```
+
+### SEE ALSO
+
+* [ortfodb](ortfodb.md)	 - Manage your portfolio's database
+
+###### Auto generated by spf13/cobra on 15-Apr-2024

docs/ortfodb_exporters.md

@@ -0,0 +1,23 @@
+## ortfodb exporters
+
+Commands related to ortfo/db exporters
+
+### Options
+
+```
+  -h, --help   help for exporters
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   config file path (default "ortfodb.yaml")
+      --scattered       Operate in scattered mode. In scattered mode, the description.md files are searched inside `.ortfo' folders in every folder of the database directory, instead of directly in the database directory's folders. See https://github.com/ortfo/
+```
+
+### SEE ALSO
+
+* [ortfodb](ortfodb.md)	 - Manage your portfolio's database
+* [ortfodb exporters init](ortfodb_exporters_init.md)	 - Create a new exporter
+
+###### Auto generated by spf13/cobra on 15-Apr-2024

docs/ortfodb_exporters_init.md

@@ -0,0 +1,26 @@
+## ortfodb exporters init
+
+Create a new exporter
+
+```
+ortfodb exporters init <name> [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for init
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   config file path (default "ortfodb.yaml")
+      --scattered       Operate in scattered mode. In scattered mode, the description.md files are searched inside `.ortfo' folders in every folder of the database directory, instead of directly in the database directory's folders. See https://github.com/ortfo/
+```
+
+### SEE ALSO
+
+* [ortfodb exporters](ortfodb_exporters.md)	 - Commands related to ortfo/db exporters
+
+###### Auto generated by spf13/cobra on 15-Apr-2024

docs/ortfodb_replicate.md

@@ -0,0 +1,36 @@
+## ortfodb replicate
+
+Replicate a database directory from a built database file.
+
+### Synopsis
+
+Replicate a database from <from-filepath> to <to-filepath>. Note that <to-filepath> must be an empty directory.
+
+Example: ortfodb replicate ./database.json ./replicated-database/
+
+WARNING: This command is still kind-of a WIP, it works but there's minimal logging and error handling.
+
+
+```
+ortfodb replicate <from-filepath> <to-filepath> [flags]
+```
+
+### Options
+
+```
+  -h, --help        help for replicate
+  -n, --no-verify   Don't try to validate the built database file before replicating
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   config file path (default "ortfodb.yaml")
+      --scattered       Operate in scattered mode. In scattered mode, the description.md files are searched inside `.ortfo' folders in every folder of the database directory, instead of directly in the database directory's folders. See https://github.com/ortfo/
+```
+
+### SEE ALSO
+
+* [ortfodb](ortfodb.md)	 - Manage your portfolio's database
+
+###### Auto generated by spf13/cobra on 15-Apr-2024

docs/ortfodb_schemas.md

@@ -0,0 +1,38 @@
+## ortfodb schemas
+
+Output JSON schemas for ortfodb's various resources
+
+### Synopsis
+
+Don't pass any resource to get the list of available resources
+
+Output the JSON schema for:
+- configuration: the configuration file (.ortfodb.yaml)
+- database: the output database file
+- tags: the tags repository file (tags.yaml)
+- technologies: the technologies repository file (technologies.yaml)
+- exporter: the manifest file for an exporter
+
+
+```
+ortfodb schemas [resource] [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for schemas
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   config file path (default "ortfodb.yaml")
+      --scattered       Operate in scattered mode. In scattered mode, the description.md files are searched inside `.ortfo' folders in every folder of the database directory, instead of directly in the database directory's folders. See https://github.com/ortfo/
+```
+
+### SEE ALSO
+
+* [ortfodb](ortfodb.md)	 - Manage your portfolio's database
+
+###### Auto generated by spf13/cobra on 15-Apr-2024

go.mod

@@ -41,6 +41,7 @@ require (
 	github.com/charmbracelet/bubbletea v0.25.0 // indirect
 	github.com/charmbracelet/lipgloss v0.10.0 // indirect
 	github.com/containerd/console v1.0.4 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.3 // indirect
 	github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect
 	github.com/go-git/go-billy/v5 v5.5.0 // indirect
 	github.com/gosuri/uilive v0.0.4 // indirect
@@ -53,6 +54,7 @@ require (
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.15.2 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
 	golang.org/x/sync v0.7.0 // indirect
 	golang.org/x/sys v0.19.0 // indirect

go.sum

@@ -34,6 +34,7 @@ github.com/charmbracelet/lipgloss v0.10.0 h1:KWeXFSexGcfahHX+54URiZGkBFazf70JNMt
 github.com/charmbracelet/lipgloss v0.10.0/go.mod h1:Wig9DSfvANsxqkRsqj6x87irdy123SR4dOXlKa91ciE=
 github.com/containerd/console v1.0.4 h1:F2g4+oChYvBTsASRTz8NP6iIAi97J3TtSAsLbIFn4ro=
 github.com/containerd/console v1.0.4/go.mod h1:YynlIjWYF8myEu6sdkwKIvGQq+cOckRm6So2avqoYAk=
+github.com/cpuguy83/go-md2man/v2 v2.0.3 h1:qMCsGGgs+MAzDFyp9LpAe1Lqy/fY/qCovCm0qnXZOBM=
 github.com/cpuguy83/go-md2man/v2 v2.0.3/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
@@ -131,6 +132,7 @@ github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJ
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/rogpeppe/go-internal v1.11.0 h1:cWPaGQEPrBb5/AsnsZesgZZ9yb1OQ+GOISoDNXVBh4M=
+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/sebdah/goldie/v2 v2.5.3 h1:9ES/mNN+HNUbNWpVAlrzuZ7jE+Nrczbj8uFRjM7624Y=
 github.com/sebdah/goldie/v2 v2.5.3/go.mod h1:oZ9fp0+se1eapSRjfYbsV/0Hqhbuu3bJVvKI/NNtssI=

manpages/ortfodb-add.1

@@ -0,0 +1,46 @@
+.nh
+.TH "ORTFODB" "1" "Apr 2024" "https://ortfo.org/db" "ortfo/db Manual"
+
+.SH NAME
+.PP
+ortfodb-add - Add a new project to your portfolio
+
+
+.SH SYNOPSIS
+.PP
+\fBortfodb add  [flags]\fP
+
+
+.SH DESCRIPTION
+.PP
+Create a new project in the appropriate folder. ID is the work's slug.
+
+
+.SH OPTIONS
+.PP
+\fB-h\fP, \fB--help\fP[=false]
+	help for add
+
+.PP
+\fB--overwrite\fP[=false]
+	Overwrite the description.md file if it already exists
+
+
+.SH OPTIONS INHERITED FROM PARENT COMMANDS
+.PP
+\fB-c\fP, \fB--config\fP="ortfodb.yaml"
+	config file path
+
+.PP
+\fB--scattered\fP[=false]
+	Operate in scattered mode. In scattered mode, the description.md files are searched inside `.ortfo' folders in every folder of the database directory, instead of directly in the database directory's folders. See https://github.com/ortfo/
+
+
+.SH SEE ALSO
+.PP
+\fBortfodb(1)\fP
+
+
+.SH HISTORY
+.PP
+15-Apr-2024 Auto generated by spf13/cobra