diff mbox series

[bug#61483,v2,5/5] DRAFT doc: Document Home Shepherd Services.

Message ID 20230216155355.11106-5-janneke@gnu.org
State New
Headers show
Series [bug#61483,v2,1/5] DRAFT gnu: home: services: Add home-git-daemon-service-type. | expand

Commit Message

Janneke Nieuwenhuizen Feb. 16, 2023, 3:53 p.m. UTC 
* doc/guix.texi (Shepherd Home Services): New subsubsection.
---
 doc/guix.texi | 124 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 123 insertions(+), 1 deletion(-)

Comments

Ludovic Courtès March 4, 2023, 5:14 p.m. UTC | #1 
"Jan (janneke) Nieuwenhuizen" <janneke@gnu.org> skribis:

> * doc/guix.texi (Shepherd Home Services): New subsubsection.

Oooh, I totally overlooked this.

Overall I’d suggest documenting in the patch that adds the service.
That way, each change is self-contained, which facilitates review, etc.

I would suggest creating one section per type, roughly corresponding to
the (gnu home services …) module: “Media”, “Version Control”, etc.  For
SSH there’s already “Secure Shell”.

Also please start each service’s documentation with a couple of
sentences giving context and possibly an example, similar to what’s done
for the existing Home services.

Could you send an updated patch series, maybe leaving out git-daemon
until we figure out whether/how to factorize it?

Thank you!

Ludo’.
Janneke Nieuwenhuizen March 5, 2023, 6:09 p.m. UTC | #2 
Ludovic Courtès writes:

> "Jan (janneke) Nieuwenhuizen" <janneke@gnu.org> skribis:
>
>> * doc/guix.texi (Shepherd Home Services): New subsubsection.
>
> Oooh, I totally overlooked this.
>
> Overall I’d suggest documenting in the patch that adds the service.
> That way, each change is self-contained, which facilitates review, etc.

Sure.

> I would suggest creating one section per type, roughly corresponding to
> the (gnu home services …) module: “Media”, “Version Control”, etc.  For
> SSH there’s already “Secure Shell”.

Done.

> Also please start each service’s documentation with a couple of
> sentences giving context and possibly an example, similar to what’s done
> for the existing Home services.

Okay.

> Could you send an updated patch series, maybe leaving out git-daemon
> until we figure out whether/how to factorize it?

Sounds good, coming right up!

Thanks,
Janneke
diff mbox series

Patch

diff --git a/doc/guix.texi b/doc/guix.texi
index 784114f0bb..a5a62010b6 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -36,7 +36,7 @@  Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
 Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner@*
 Copyright @copyright{} 2016 John Darrington@*
 Copyright @copyright{} 2016, 2017 Nikita Gillmann@*
-Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@*
+Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2023 Jan Nieuwenhuizen@*
 Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller@*
 Copyright @copyright{} 2016 Alex ter Weele@*
 Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@*
@@ -41285,6 +41285,128 @@  mechanism instead (@pxref{Shepherd Services}).
 @end table
 @end deftp
 
+@menu
+* Shepherd Home Services::
+@end menu
+
+@node Shepherd Home Services
+@subsubsection e Shepherd Home Services
+
+The @code{(gnu home services shepherd-xyz)} module provides serveral
+home shepherd services.
+
+@defvr {Scheme Variable} home-git-daemon-service-type
+This is the type of the @code{git daemon} home service, whose value is an
+@code{home-git-daemon-configuration} object.
+@end defvr
+
+@deftp {Data Type} home-git-daemon-configuration
+Available @code{home-git-daemon-configuration} fields are:
+
+@table @asis
+@item @code{git} (default: @code{git}) (type: file-like)
+The git package to use.
+
+@item @code{root} (default: @file{@env{XDG_DATA_HOME}/git-daemon}) (type: string)
+The git deamon's base directory.
+
+@item @code{export-all?} (default: @code{#f})
+Whether to allow access for all Git repositories, even if they do not
+have the @file{git-daemon-export-ok} file.
+
+@item @code{base-path} (default: @file{/srv/git})
+Whether to remap all the path requests as relative to the given path.
+If you run @command{git daemon} with @code{(base-path "/srv/git")} on
+@samp{example.com}, then if you later try to pull
+@indicateurl{git://example.com/hello.git}, git daemon will interpret the
+path as @file{/srv/git/hello.git}.
+
+@item @code{user-path} (default: @code{#f})
+Whether to allow @code{~user} notation to be used in requests.  When
+specified with empty string, requests to
+@indicateurl{git://host/~alice/foo} is taken as a request to access
+@code{foo} repository in the home directory of user @code{alice}.  If
+@code{(user-path "@var{path}")} is specified, the same request is taken
+as a request to access @file{@var{path}/foo} repository in the home
+directory of user @code{alice}.
+
+@item @code{listen} (default: @code{'()})
+Whether to listen on specific IP addresses or hostnames, defaults to
+all.
+
+@item @code{port} (default: @code{#f})
+Whether to listen on an alternative port, which defaults to 9418.
+
+@item @code{whitelist} (default: @code{'()})
+If not empty, only allow access to this list of directories.
+
+@item @code{extra-options} (default: @code{'()})
+Extra options will be passed to @command{git daemon}, please run
+@command{man git-daemon} for more information.
+
+@end table
+@end deftp
+
+@defvr {Scheme Variable} home-kodi-service-type
+This is the type of the @code{git daemon} home service, whose value is an
+@code{home-kodi-configuration} object.
+@end defvr
+
+@deftp {Data Type} home-kodi-configuration
+Available @code{home-kodi-configuration} fields are:
+
+@table @asis
+@item @code{git} (default: @code{git}) (type: file-like)
+The git package to use.
+
+@item @code{extra-options} (default: @code{'()})
+Extra options will be passed to @command{kodi}, please run @command{man
+kodi} for more information.
+
+@end table
+@end deftp
+
+@defvr {Scheme Variable} home-ssh-agent-service-type
+This is the type of the @code{git daemon} home service, whose value is an
+@code{home-ssh-agent-configuration} object.
+@end defvr
+
+@deftp {Data Type} home-ssh-agent-configuration
+Available @code{home-ssh-agent-configuration} fields are:
+
+@table @asis
+@item @code{git} (default: @code{git}) (type: file-like)
+The git package to use.
+
+@item @code{socket-dir} (default: @code{@env{XDG_RUNTIME_DIR}/ssh-agent"}) (type: string)
+The directory to write the ssh-agent's @file{socket} file.
+
+@item @code{extra-options} (default: @code{'()})
+Extra options will be passed to @command{ssh-agent}, please run
+@command{man ssh-agent} for more information.
+
+@end table
+@end deftp
+
+@defvr {Scheme Variable} home-znc-service-type
+This is the type of the @code{git daemon} home service, whose value is an
+@code{home-znc-configuration} object.
+@end defvr
+
+@deftp {Data Type} home-znc-configuration
+Available @code{home-znc-configuration} fields are:
+
+@table @asis
+@item @code{git} (default: @code{git}) (type: file-like)
+The git package to use.
+
+@item @code{extra-options} (default: @code{'()})
+Extra options will be passed to @command{znc}, please run @command{man
+znc} for more information.
+
+@end table
+@end deftp
+
 @node Secure Shell
 @subsection Secure Shell