From 749cdfad1da20c7dd63ec04bf43f83ec708b2b30 Mon Sep 17 00:00:00 2001
From: Filip Lajszczak <filip@lajszczak.dev>
Date: Sun, 12 Nov 2023 14:44:53 +0000
Subject: doc: Document publishers.

---
 doc/haunt.texi | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 113 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/haunt.texi b/doc/haunt.texi
index 3deba4c..68229fc 100644
--- a/doc/haunt.texi
+++ b/doc/haunt.texi
@@ -156,6 +156,14 @@ later (for Skribe support)
 @item
 @url{https://github.com/OrangeShark/guile-commonmark, guile-commonmark}
 version 0.1 or later (for CommonMark support)
+@item
+@url{https://rsync.samba.org/, rsync}
+version 0.2 or later (for rsync publishing)
+@item
+@url{https://sr.ht/~emersion/hut/, hut}
+version 0.2 or later (for Sourcehut publishing)
+@item
+@url{https://www.gnu.org/software/tar/, Tar} (for Sourcehut publishing)
 @end itemize
 
 @node Building
@@ -291,6 +299,7 @@ programming interfaces.
 @menu
 * Invoking haunt build::        Build the website.
 * Invoking haunt serve::        Serve the website over HTTP.
+* Invoking haunt publish::      Publish the website.
 @end menu
 
 The Haunt command-line interface is composed of many subcommands.  The
@@ -366,6 +375,32 @@ Automatically rebuild the site when source files change.
 
 @end table
 
+@node Invoking haunt publish
+@section Invoking @command{haunt publish}
+
+The @command{haunt publish} command deploys the site to a remote
+location.  The site must have already been built via @command{haunt
+build} before running @command{haunt publish}.
+
+Usage:
+
+@example
+haunt publish
+@end example
+
+By default, Haunt uses the publisher named @code{production} defined
+for the current site.  However, Haunt supports multiple publishers.
+Consider the use case where an author wants to publish to a staging
+environment to confirm that everything looks good on a real web server
+before publishing to production.  To use a non-production publisher,
+simply say so at the command line:
+
+@example
+haunt publish staging
+@end example
+
+For details on how to configure publishers, @pxref{Publishers}.
+
 @node Programming Interface
 @chapter Programming Interface
 
@@ -376,6 +411,7 @@ Automatically rebuild the site when source files change.
 * Pages::                       HTML/XML pages.
 * Assets::                      Images, stylesheets, etc.
 * Builders::                    Web page builders.
+* Publishers::                  How to publish your site.
 @end menu
 
 Haunt is a fully-programmable system composed of several Guile Scheme
@@ -398,7 +434,7 @@ output files are written to, etc.
        [#:file-filter @code{default-file-filter}] @
        [#:build-directory "site"] [#:default-metadata '()] @
        [#:make-slug @code{post-slug}] [#:readers '()] @
-       [#:builders '()]
+       [#:builders '()] [#:publishers '()]
 Create a new site object.  All arguments are optional:
 
 @table @var
@@ -430,6 +466,9 @@ A list of reader objects for processing posts.
 @item builders
 A list of procedures for building pages from posts.
 
+@item publishers
+A list of publisher objects for upload site contents to a remote location
+
 @end table
 
 @end deffn
@@ -470,6 +509,11 @@ Return the list of reader procedures for @var{site}.
 Return the list of builder procedures for @var{site}.
 @end deffn
 
+@deffn {Scheme Procedure} site-publishers @var{site}
+Return the list of publisher objects for upload @var{site} contents to a
+remote location.
+@end deffn
+
 @node Posts
 @section Posts
 
@@ -981,6 +1025,74 @@ The maximum number of posts to render in each feed.  The default is
 
 @end deffn
 
+@node Publishers
+@section Publishers
+
+@example
+(use-modules (haunt publisher))
+@end example
+
+The purpose of a publisher is to deploy a built site.  Haunt comes
+with some built-in publishers, but custom publishers can be created
+with the following interface.
+
+@deffn {Scheme Procedure} make-publisher @var{name} @var{proc}
+Create a new publisher.
+@end deffn
+
+@deffn {Scheme Procedure} publisher? @var{object}
+Return @code{#t} if @var{object} is a publisher.
+@end deffn
+
+@deffn {Scheme Procedure} publisher-name @var{publisher}
+Return the publisher name.
+@end deffn
+
+@deffn {Scheme Procedure} publisher-proc @var{reader}
+Return the publisher procedure for @var{publisher}.
+@end deffn
+
+@deffn {Scheme Procedure} publish @var{publisher} @var{site}
+Publish @var{site} with @var{publisher}.
+@end deffn
+
+@deffn {Scheme Procedure} run-command  @var{program} @var{args}
+Run command @var{program} with @var{args} arguments.
+@end deffn
+
+Haunt comes with the following built-in publishers:
+
+@node Rsync
+@subsection Rsync
+
+@example
+(use-modules (haunt publisher rsync))
+@end example
+
+@deffn {Scheme Procedure} rsync-publisher [#:name 'production] [#:destination] @@
+       [#:user] [#:host] [#:name] [#:rsync] @@
+       [#:flags '("--compress" "--delete" "--progress" "--recursive" "--verbose")]
+
+Return a new publisher named @var{name} that publishes a site to
+@var{destination}, either locally or to a remote host if @var{host}
+and/or @var{user} arguments are specified.  Passing @var{rsync}
+overrides the @command{rsync} executable used.  Passing @var{flags}
+overrides the set of command line flags used.
+@end deffn
+
+@node Sourcehut
+@subsection Sourcehut
+@example
+(use-modules (haunt publisher sourcehut))
+@end example
+
+@deffn {Scheme Procedure} sourcehut-publisher [#:name 'production] [#:hut] [#:tar]
+Return a new publisher named @var{name} that publishes a site to
+Sourcehut pages using the site's configured domain.  Passing @var{hut}
+and/or @var{tar} overrides the default @command{hut} and @command{tar}
+executables used.
+@end deffn
+
 @node Contributing
 @chapter Contributing
 
-- 
cgit v1.2.3