From d34847784104e75d54c4e2643cdb27d6441ff38a Mon Sep 17 00:00:00 2001 From: Alberto Bertogli Date: Mon, 5 Aug 2019 14:14:55 +0100 Subject: [PATCH] docs: Integrate with readthedocs.org This patch adds configuration to integrate with readthedocs.org, using mkdocs as rendering engine. It also does minor documentation updates, to tidy some things up (clearer titles, move some documentation from the root into docs/, etc). --- .mkdocs.yml | 29 +++++++++++++++++++++++++++++ .readthedocs.yml | 8 ++++++++ README.md | 9 ++++++--- docs/howto.md | 2 +- docs/index.md | 24 ++++++++++++++++++++++++ INSTALL.md => docs/install.md | 0 docs/man/index.md | 29 +++++++++++++++++++++++++++++ docs/monitoring.md | 2 +- UPGRADING.md => docs/upgrading.md | 0 9 files changed, 98 insertions(+), 5 deletions(-) create mode 100644 .mkdocs.yml create mode 100644 .readthedocs.yml create mode 100644 docs/index.md rename INSTALL.md => docs/install.md (100%) create mode 100644 docs/man/index.md rename UPGRADING.md => docs/upgrading.md (100%) diff --git a/.mkdocs.yml b/.mkdocs.yml new file mode 100644 index 0000000..a624b41 --- /dev/null +++ b/.mkdocs.yml @@ -0,0 +1,29 @@ +# mkdocs configuration +# +# To test changes locally, run: +# mkdocs serve -f .mkdocs.yml + +site_name: chasquid documentation + +# Point the repo to github to make it easier for users to do edits, even if +# it's not the canonical location. +repo_url: https://github.com/albertito/chasquid + +markdown_extensions: + - codehilite: + guess_lang: false + +theme: readthedocs + +nav: +- Home: index.md +- How-to: howto.md +- Install: install.md +- Manpages: man/index.md +- All: + - hooks.md + - dovecot.md + - dkim.md + - flow.md + - monitoring.md + diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..2cfa631 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,8 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details. +version: 2 + +mkdocs: + configuration: .mkdocs.yml + + diff --git a/README.md b/README.md index 6a09920..a04e7f6 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ It's written in [Go](https://golang.org), and distributed under the [![Go Report Card](https://goreportcard.com/badge/github.com/albertito/chasquid)](https://goreportcard.com/report/github.com/albertito/chasquid) [![Coverage Status](https://coveralls.io/repos/github/albertito/chasquid/badge.svg?branch=next)](https://coveralls.io/github/albertito/chasquid?branch=next) [![GoDoc](https://godoc.org/blitiri.com.ar/go/chasquid?status.svg)](https://godoc.org/blitiri.com.ar/go/chasquid) +[![Documentation Status](https://readthedocs.org/projects/chasquid/badge/?version=latest)](https://chasquid.readthedocs.io/en/latest/?badge=latest) [![Freenode](https://img.shields.io/badge/chat-freenode-brightgreen.svg)](https://webchat.freenode.net?channels=%23chasquid) @@ -52,9 +53,11 @@ It's written in [Go](https://golang.org), and distributed under the ## Documentation -The [Debian+Dovecot+chasquid how-to](docs/howto.md) and the -[installation guide](INSTALL.md) -are the best starting points on how to install, configure and run chasquid. +The [how-to guide](docs/howto.md) and the [installation +guide](docs/install.md) are the best starting points on how to install, +configure and run chasquid. + +You will find [all documentation here](https://chasquid.readthedocs.io). ## Contact diff --git a/docs/howto.md b/docs/howto.md index 33b8032..0457aa6 100644 --- a/docs/howto.md +++ b/docs/howto.md @@ -1,5 +1,5 @@ -# Setting up an email server with Debian, dovecot and chasquid +# chasquid how-to guide This is a practical guide for setting up an email server for personal or small groups use. It does not contain many explanations, but includes links to more diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..58e58ab --- /dev/null +++ b/docs/index.md @@ -0,0 +1,24 @@ + +# chasquid + +[chasquid](https://blitiri.com.ar/p/chasquid) is an SMTP (email) server with a +focus on simplicity, security, and ease of operation. + +This is the documentation index. + +Please see the [project page](https://blitiri.com.ar/p/chasquid) for more +details. + + +## Contact + +If you have any questions, comments or patches please send them to the [mailing +list](https://groups.google.com/forum/#!forum/chasquid), +chasquid@googlegroups.com. + +To subscribe, send an email to chasquid+subscribe@googlegroups.com. + +You can also reach out via IRC, `#chasquid` on +[freenode](https://freenode.net/). + + diff --git a/INSTALL.md b/docs/install.md similarity index 100% rename from INSTALL.md rename to docs/install.md diff --git a/docs/man/index.md b/docs/man/index.md new file mode 100644 index 0000000..5c503db --- /dev/null +++ b/docs/man/index.md @@ -0,0 +1,29 @@ +# Manual pages + +From the latest Debian package: + +- [chasquid(1)](https://manpages.debian.org/unstable/chasquid/chasquid.1): + the main binary. +- [chasquid.conf(5)](https://manpages.debian.org/unstable/chasquid/chasquid.conf.5): + the configuration file and structure. +- [chasquid-util(1)](https://manpages.debian.org/unstable/chasquid/chasquid-util.1): + the command-line utility helper. +- [mda-lmtp(1)](https://manpages.debian.org/unstable/chasquid/mda-lmtp.1): + helper to integrate with LMTP delivery. +- [smtp-check(1)](https://manpages.debian.org/unstable/chasquid/smtp-check.1): + SMTP setup checker. + +From the development branch (more likely to change, but useful when doing +development or running experimental versions): + +- [chasquid(1)](https://github.com/albertito/chasquid/blob/next/docs/man/chasquid.1.pod): + the main binary. +- [chasquid.conf(5)](https://github.com/albertito/chasquid/blob/next/docs/man/chasquid.conf.5.pod): + the configuration file and structure. +- [chasquid-util(1)](https://github.com/albertito/chasquid/blob/next/docs/man/chasquid-util.1.pod): + the command-line utility helper. +- [mda-lmtp(1)](https://github.com/albertito/chasquid/blob/next/docs/man/mda-lmtp.1.pod): + helper to integrate with LMTP delivery. +- [smtp-check(1)](https://github.com/albertito/chasquid/blob/next/docs/man/smtp-check.1.pod): + SMTP setup checker. + diff --git a/docs/monitoring.md b/docs/monitoring.md index aedcf0c..d217b8a 100644 --- a/docs/monitoring.md +++ b/docs/monitoring.md @@ -31,7 +31,7 @@ endpoint for expvars). *Note these are still subject to change, although breaking changes will be avoided whenever possible, and will be noted in the [upgrading -notes](../UPGRADING.md).* +notes](upgrading.md).* List of exported variables: diff --git a/UPGRADING.md b/docs/upgrading.md similarity index 100% rename from UPGRADING.md rename to docs/upgrading.md