From 927e9c97c932eefb3539f7741f6c927c01a4a202 Mon Sep 17 00:00:00 2001 From: Arun Isaac Date: Fri, 25 Feb 2022 17:52:47 +0530 Subject: doc: Add Reference chapter. * doc/forge.skb (Reference): New chapter. --- doc/forge.skb | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 73 insertions(+), 1 deletion(-) (limited to 'doc/forge.skb') diff --git a/doc/forge.skb b/doc/forge.skb index 723d47f..59640a6 100644 --- a/doc/forge.skb +++ b/doc/forge.skb @@ -51,4 +51,76 @@ and the rest are simple files that can be backed up easily.]) email. guix-forge acknowledges this and prefers to support git's ,(ref :url "https://drewdevault.com/2018/07/02/Email-driven-git.html" :text "email driven workflow") with project discussion, bug reports -and patches all happening over email.])))) +and patches all happening over email.]))) + (chapter :title [Reference] + (description + (record-documentation "forge/forge.scm" ' + (record-field "projects" + [List of ,(ref :mark "" :text +(code [])) objects describing projects managed by +guix-forge])) + (record-documentation "forge/forge.scm" ' + (record-field "name" + [Name of the project]) + (record-field "repository" + [Path to a local git repository, or URI to a remote git +repository]) + (record-field "user" + [User who owns the repository if it is local. This field is +disregarded if the repository is remote.]) + (record-field "description" + [Short one-line description of the project. It is used to set +the ,(file "description") file in the repository and will appear in +the cgit web interface.]) + (record-field "website-directory" + [Path to the document root of the project website. Its +ownership is granted to the ,(code "laminar") user so that continuous +integration jobs can write to it.]) + (record-field "ci-jobs" + [List of ,(ref :mark "") objects +describing ,(abbr :short "CI" :long "continuous integration") jobs to +configure]) + (record-field "ci-jobs-trigger" + [One of ,(code ['post-receive-hook]), ,(code ['webhook]), or +,(code ['cron]) representing the type of trigger for continuous +integration jobs. +,(description + (item :key (code ['post-receive-hook]) + [If ,(code ['post-receive-hook]) is specified, the ,(file +"post-receive-hook") of the repository is configured to trigger CI +jobs. This is possible only for local repositories. Note that any +pre-existing ,(file "post-receive-hook") is overwritten.]) + (item :key (code ['webhook]) [If ,(code +['webhook]) is specified, a webhook server is configured to trigger CI +jobs when a request is received on ,(samp "http://hostname:port/hooks/") \.]) + (item :key (code ['cron]) [If ,(code ['cron]) is +specified ,a cron job triggers the CI jobs once a day.]))] + :default [,(code ['post-receive-hook]) for local repositories +and ,(code ['cron]) for remote repositories]) + (record-field "repository-branch" + [Main branch of the repository])) + (record-documentation "forge/laminar.scm" ' + (record-field "name" + [Name of the job]) + (record-field "run" + [G-expression to be run]) + (record-field "after" + [G-expression to be run after the main job script])) + (record-documentation "forge/webhook.scm" ' + (record-field "package" + [,(code [webhook]) package to use]) + (record-field "ip" + [IP address to listen on]) + (record-field "port" + [Port to listen on]) + (record-field "log-directory" + [Directory to write log files to]) + (record-field "hooks" + [List of ,(ref :mark "" :text (code +[])) objects describing hooks to configure])) + (record-documentation "forge/webhook.scm" ' + (record-field "id" + [Identifier of the webhook. This hook is triggered at ,(ref +:url [http://host:port/hooks/]).]) + (record-field "run" + [G-expression to run when the webhook is triggered]))))) -- cgit v1.2.3