Author: Pedro Lucas Porcellis <porcellis@eletrotupi.com>
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.
.gitignore | 2 + Makefile | 15 ++++++-- README.md | 2 + docs/smithy.1.scd | 40 +++++++++++++++++++++++ docs/smithy.yml.5.scd | 77 +++++++++++++++++++++++++++++++++++++++++++++
diff --git a/.gitignore b/.gitignore index 28bf40089f5f6c0aca207626b2d6a2bb2043152f..8ba024392f63c3232846d43c6a6c5683357978b5 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ bin pkg/statik smithy.yml smithy +smithy.1 +smithy.yml.5 diff --git a/Makefile b/Makefile index a8972fe23e1bed2e4553aae8742b4e104e133c9e..9ebc2338bc77f65b84b6a9f5b23cb257992f0c40 100644 --- a/Makefile +++ b/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.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 diff --git a/README.md b/README.md index 20731a92a28b7fc875bee8f3e5ef2620ef3d270b..1e209a08f84ecbed690c75f05ecbc193cb3e3d05 100644 --- a/README.md +++ b/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 diff --git a/docs/smithy.1.scd b/docs/smithy.1.scd new file mode 100644 index 0000000000000000000000000000000000000000..79c0ebeafdcb179ca474096f57c33166ed8bda45 --- /dev/null +++ b/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 <honza@pokorny.ca>, who is assisted by other free +software contributors. For more information about smithy development, see +https://github.com/honza/smithy. diff --git a/docs/smithy.yml.5.scd b/docs/smithy.yml.5.scd new file mode 100644 index 0000000000000000000000000000000000000000..a36f6c160a02f75e2a274d33c5e7446945e4bc02 --- /dev/null +++ b/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 <honza@pokorny.ca>, who is assisted by other free +software contributors. For more information about smithy development, see +https://github.com/honza/smithy.