Add documentation

Documentation is available in docs in the format of a scdoc file.
Within each release, it should be run `make docs` which will convert the
file to a traditional troff page which will be included in the final
tarball and installed if available.

Author: pedrolucasp

.gitignore

@@ -3,3 +3,5 @@ bin
 pkg/statik
 smithy.yml
 smithy
+smithy.1
+smithy.yml.5

Makefile

@@ -1,8 +1,10 @@
 BUILD_VERSION ?= $(shell git describe --always --abbrev=40 --dirty)
 
+SCDOC = scdoc
 PREFIX?=/usr/local
 BINDIR?=$(PREFIX)/bin
 SHAREDIR?=$(PREFIX)/share/smithy
+MANDIR?=$(PREFIX)/share/man
 
 LDFLAGS="-X github.com/honza/smithy/cmd.SmithyVersion=${BUILD_VERSION}"
 MODCACHE := $(shell go env GOMODCACHE)
@@ -18,10 +20,16 @@ smithy: bin/statik include/*.html
 smithy.yml:
 	./smithy generate > smithy.yml
 
+docs:
+	$(SCDOC) < docs/smithy.1.scd > smithy.1
+	$(SCDOC) < docs/smithy.yml.5.scd > smithy.yml.5
+
 install: all
 	mkdir -m755 -p $(DESTDIR)$(BINDIR) $(DESTDIR)$(SHAREDIR)
-	install -m755 smithy $(DESTDIR)$(BINDIR)/smithy
-	install -m644 smithy.yml $(DESTDIR)$(SHAREDIR)/smithy.yml
+	cp -f smithy $(DESTDIR)$(BINDIR)/smithy
+	cp -f smithy.yml $(DESTDIR)$(SHAREDIR)/smithy.yml
+	cp -f smithy.1 $(DESTDIR)$(MANDIR)/man1/smithy.1 2>/dev/null || true
+	cp -f smithy.yml.5 $(DESTDIR)$(MANDIR)/man5/smithy.yml.5 2>/dev/null || true
 
 uninstall: all
 	rm -r $(DESTDIR)$(BINDIR)/smithy
@@ -36,8 +44,7 @@ gofmt:
 	go fmt ./pkg/... ./cmd/...
 
 clean:
-	rm smithy smithy.yml
-	rm -rf pkg/statik
+	rm -rf smithy smithy.yml pkg/statik smithy.1 smithy.yml.5
 
 .PHONY:
 	smithy smithy.yml clean

README.md

@@ -20,6 +20,8 @@ Building
 -------------------------------------------------------------------------------
 
 The only dependency is [Golang](https://golang.org/) 1.15 or higher.
+Contributors to smithy should have the optional
+[scdoc](https://sr.ht/~sircmpwn/scdoc) for generating documentation.
 
 ```
 $ git clone https://github.com/honza/smithy

docs/smithy.1.scd

@@ -0,0 +1,40 @@
+smithy(1)
+
+# NAME
+
+smithy - a small git forge
+
+# SYNOPSIS
+
+*smithy* _command_ [<_options_>...]
+
+# DESCRIPTION
+
+*smithy* is a web frontend for git repositories. It's implemented entirely in
+Golang, compiles to a single binary, and it's fast and easy to deploy. Smithy
+is an alternative to cgit or gitweb, and doesn't seek to compete with Gitea and
+the like.
+
+# COMMANDS
+
+*generate*
+	Generate a sample configuration file, outputs to *STDOUT*.
+	Check *smithy.yml(5)* for more information.
+
+*serve --config path/to/config.toml*
+	Serve the application, you'll need to supply a configuration file.
+	Outputs its log to *STDOUT*.
+
+# GLOBAL FLAGS
+
+*--debug*
+	Display debug messages to *STDOUT*.
+
+*--config <path>*
+	Use the given configuration file. See *smithy.yml(5)* for a reference.
+
+# AUTHORS
+
+Maintained by Honza Pokorny <[email protected]>, who is assisted by other free
+software contributors. For more information about smithy development, see
+https://github.com/honza/smithy.

docs/smithy.yml.5.scd

@@ -0,0 +1,77 @@
+smithy.yml(5)
+
+# NAME
+
+*smithy.yml* - configuration file for *smithy*(1)
+
+# DESCRIPTION
+
+This file describes where smithy should scan for repositories, their
+respectives titles, description and slug. Also if it should include the default
+styles and assets or if it should load from a respective directory.
+
+# GLOBAL DIRECTIVES
+
+*host: <address>*
+	Address will be displayed on a repository, indicating the URL he can use
+	to clone.
+
+*port: <...>*
+	Port to serve smithy from. You can use a reverse-proxy (nginx, apache) to
+	expose smithy.
+
+# GIT DIRECTIVES
+
+*root: <path>*
+	The main directory where smithy should scan for repositories.
+
+*repos*
+	A list of repositories and their respective configurations.
+
+# STATIC DIRECTIVES
+
+If you'd like to customize the templates or the css, you can grab the source
+code, copy the `include` directory somewhere, and then set `root`, and
+`templates.dir` to that directory.
+
+*root: <path>*
+	When set to an empty string, it will load the static assets bundled within
+	the project.
+
+*prefix: <path>*
+	A given prefix that all assets will receive.
+
+# TEMPLATES DIRECTIVES
+
+*dir: <path>*
+	The directory to load templates from.
+
+# EXAMPLE CONFIGURATION
+
+When manually building smithy from source, a sample config file will be
+included on `/usr/local/share/smithy/smithy.yml`.
+
+```
+title: Smithy, a lightweight git force
+description: Publish your git repositories with ease
+host: git.example.com
+port: 3456
+git:
+  root: "/srv/git"
+  repos:
+    - path: "git"
+      slug: "git"
+      title: "git"
+      description: "git is a fast, scalable distributed revision control system"
+static:
+  root: ""
+  prefix: /static/
+templates:
+  dir: ""
+```
+
+# AUTHORS
+
+Maintained by Honza Pokorny <[email protected]>, who is assisted by other free
+software contributors. For more information about smithy development, see
+https://github.com/honza/smithy.