WIP documentation.

doc/service.1.scd

@@ -0,0 +1,117 @@
+service(1)
+
+# NAME
+
+service - system services control and querying interface
+
+# SYNOPSIS
+
+*service* add <service> [options]
+
+*service* start <service>
+
+*service* stop <service>
+
+*service* status [-v] [service [service [...]]
+
+*service* reload <service>
+
+*service* del <service>
+
+*service* show <service>
+
+# DESCRIPTION
+
+**service** is a tool that starts, stops, lists, queries, creates or removes system services.
+**service** abstracts their configuration and handles their dependencies to one another.
+
+Some general concepts about WeirdOS’ services management and boot procedure can be found in *service*(7).
+
+# USAGE
+
+## Identifying Services
+
+	service show <id>
+
+	service status [-v|--verbose] [id [id [...]]]
+
+Service ids are the name of a service, that may be prefixed by the name of their environment and a slash ('/').
+
+*service show* shows all of a service’s relationship to other services as well as its full configuration as handled by `service`.
+
+*service status* shows the status of one or multiple services, including whether they are currently running or not.
+If no parameter is provided to the `status` command, it will show the status of all services.
+If the `--verbose` flag is provided, informations about what tokens a service produces or consumes, as well as the ports it reserves, will be displayed as well.
+
+## Starting Services
+
+	service start <id>
+
+If a service that has dependencies is requested to be started, its dependencies will be started beforehand.
+
+If a service is depended on by a non-runnable service, the non-runnable services will have their configuration and deployable files generated once its last dependency is started.
+An example for this is a static website that depends on a web server: if the web server is started, the static website’s files and possible configuration will be generated or installed where they will be served.
+
+## Stopping Services
+
+	service stop <id>
+
+## Adding Services
+
+	service add <id> [options]
+
+The **service add** command can be used to create a service.
+Only services that have been “added” to the list of known services can be started.
+
+It takes as first parameter the *id* of the service to create.
+
+The service type defaults to the name of the service to be created.
+
+## Removing Services
+
+	service del <id> [options]
+
+The **service del** command removes a service from the system.
+Be careful, as this command also removes its configuration and data.
+
+*service del* will not let you remove services that are being depended on unless you provide a `--force` flag.
+
+*service del* will stop services before removing them.
+
+# EXAMPLES
+
+## Starting a Service
+
+	$ service start gitea
+
+## Registering a Single Service
+
+	service add postgresql
+
+	service start postgresql
+
+## Registering Multiple Services with Dependencies
+
+	service add nginx
+
+	service add postgresql
+
+	service add gitea http=nginx postgresql=postgresql domain=gitea.test
+
+In this example, the dependencies of the “gitea” service could have been guessed automatically.
+The following example does the exact same thing but lets `service` guess dependencies.
+
+	service add nginx
+
+	service add postgresql
+
+	service add gitea domain=gitea.test
+
+# SEE ALSO
+
+*servîce*(7)
+
+# AUTHORS
+
+Luka Vandervelden <lukc@upyum.com>
+

doc/service.7.scd

@@ -0,0 +1,52 @@
+service(7)
+
+# NAME
+
+service - services and applications management
+
+# DESCRIPTION
+
+The *service*(1) tool is used to manage services.
+
+The *rc*(1) script is used to start the components of the system not handled by *init*(1).
+*rc* is usually the first application to call *service*.
+
+# SERVICE IDS
+
+Service ids are the name of a service, that may be prefixed by the name of their environment and a slash ('/').
+
+The default environment for services, if none is provided, is named *root*.
+
+# TOKENS
+
+Interactions between services is represented by *tokens*.
+Their names and behavior are arbitrary, and they only serve in establishing conventions between services.
+
+# FILES
+
+## /etc/rc/services
+
+Directory in which the metadata about instances of services handled by *service*(1) are stored.
+
+## /etc/rc/environments
+
+Directory in which the metadata about environments of services handled by *service*(1) are stored.
+
+The *root* environment is virtual and does not have a matching entry.
+
+## /usr/weirdos/share/services
+
+Directory in which the behavior of services is stored.
+
+## /usr/weirdos/share/templates
+
+Directory in which configuration templates to be used by service’s *gen-config* are stored.
+
+# SEE ALSO
+
+*spec*(5)
+
+# AUTHORS
+
+Luka Vandervelden <lukc@upyum.com>
+

project.zsh

@@ -45,6 +45,14 @@ for file in utils/*; do
 	type[$file]=script
 done
 
+for file in doc/*; do
+	[[ "$file" =~ .*\.scd$ ]] || continue
+
+	targets+=(${file%.scd})
+	type[${file%.scd}]=scdoc
+	sources[${file%.scd}]=${file}
+done
+
 # FIXME: This should be upstreamed.
 function script.install {
 	if [[ "false" = "${install[$target]}" ]]; then
@@ -56,3 +64,38 @@ function script.install {
 
 install[status]='$(LIBEXECDIR)/service'
 
+function scdoc.prelude {
+	for target in $targets; do
+		[[ "${type[$target]}" == "scdoc" ]] || continue
+
+		if [[ -z "${install[$target]}" ]]; then
+			local section="${file%.scd}"
+			section="${section#*.}"
+
+			install[$target]="\$(SHAREDIR)/man/man${section}"
+		fi
+	done
+}
+
+function SCD {
+	SED "$@" | sed 's|SED|SCD|'
+}
+
+function scdoc.build {
+	write "${target}: ${sources[$target]}"
+	write "\t@echo '$(SCD $target)'"
+	write "\t${Q}scdoc < ${sources[$target]} > $target || rm $target"
+}
+
+function scdoc.install {
+	script.install "$@"
+}
+
+function scdoc.uninstall {
+	script.uninstall "$@"
+}
+
+function scdoc.clean {
+	script.clean "$@"
+}
+