Merge pull request #6548 from phil-hands/add_docs

Add docs: man pages and systemd Documentation= settings

Author: mergify[bot]

Makefile

@@ -60,6 +60,38 @@ help:
 	@sed -n 's/\(^[^.#[:space:]A-Z]*\):.*$$/\1/p' Makefile | uniq
 	@echo See docs/Contributing.asciidoc for more details
 
+man_names = openqa-cli openqa-client openqa-load-templates openqa-dump-templates openqa-clone-job openqa-validate-yaml openqa-label-all
+manpages = $(addprefix $(man_dir)/,$(addsuffix .1,$(man_names)))
+man_dir = build/man1
+
+$(man_dir):
+	mkdir -p $@
+
+define run-pod2man =
+pod2man --errors=stderr --section=1 \
+	--center "openQA Documentation" \
+	--name=$(notdir $(basename $@)) $< $@
+endef
+
+$(man_dir)/openqa-label-all.1: script/openqa-label-all
+	argparse-manpage --pyfile $< --function get_parser --author "various authors:" --author-email "https://progress.opensuse.org/projects/openqav3" --project-name openqa --url "https://github.com/os-autoinst/openQA" | grep -v '^\.br$$' >$@
+
+$(man_dir)/openqa-%.1 $(man_dir)/%.1: script/%
+	$(run-pod2man)
+
+$(man_dir)/openqa-%-templates.1: script/%_templates
+	$(run-pod2man)
+
+$(man_dir)/openqa-cli.1: lib/OpenQA/CLI.pm
+	$(run-pod2man)
+
+.PHONY: build-manpages
+build-manpages: $(man_dir) $(manpages)
+
+.PHONY: clean
+clean:
+	-rm -r build
+
 .PHONY: install-generic
 install-generic:
 	./tools/generate-packed-assets

dependencies.yaml

@@ -27,6 +27,7 @@ assetpack_requires:
 
 build_requires:
   perl(CSS::Sass):
+  python3-argparse-manpage:
   npm:
   '%assetpack_requires':
 

dist/rpm/openQA.spec

@@ -74,7 +74,7 @@
 %define build_requires %assetpack_requires npm rubygem(sass) >= 3.7.4
 %else
 # The following line is generated from dependencies.yaml
-%define build_requires %assetpack_requires npm perl(CSS::Sass)
+%define build_requires %assetpack_requires npm perl(CSS::Sass) python3-argparse-manpage
 %endif
 
 # All requirements needed by the tests executed during build-time.

script/openqa-label-all

@@ -21,10 +21,12 @@ class CustomFormatter(
 
     pass
 
-
-def parse_args():
+def get_parser():
     parser = argparse.ArgumentParser(
-        description=__doc__, formatter_class=CustomFormatter
+        prog='openqa-label-all',
+        description=""".B openqa-label-all
+allows comments to be applied to a set jobs, which match the specified options, on the specified server.""",
+        formatter_class=CustomFormatter
     )
     parser.add_argument(
         "-v",
@@ -61,6 +63,10 @@ def parse_args():
         action="store_true",
         help="Do not restart the jobs after labelling",
     )
+    return parser
+
+def parse_args():
+    parser = get_parser()
     args = parser.parse_args()
     verbose_to_log = {
         0: logging.CRITICAL,

script/openqa-validate-yaml

@@ -19,6 +19,52 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+=head1 NAME
+
+openqa-validate-yaml - check YAML files against a schema
+
+=head1 SYNOPSIS
+
+openqa-validate-yaml [I<OPTIONS>] [-] [I<file> ...]
+
+=head1 DESCRIPTION
+
+B<openqa-validate-yaml>
+should be given a list of one or more filenames.
+The files are expected to be YAML files.
+B<openqa-validate-yaml>
+tests each item in the list to see
+if the files are valid when checked against a Schema.
+
+'-' can be specified instead of a filename
+to read the test input from STDIN.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--validate-schema>
+
+Validate the Schema file itself, in addition to any YAML files.
+
+=item B<--schema-file>=I<SCHEMA>
+
+Specify the schema file or URL to validate against (default .../public/schema/JobTemplates-01.yaml)'],
+
+=item B<-h>
+
+Print a usage message, and exit.
+
+=back
+
+=head1 AUTHOR
+
+This manual page was written by Philip Hands <phil@hands.com>,
+for the Debian GNU/Linux system (but may be used by others).
+
+=cut
+
+
 use strict;
 use warnings;
 use 5.010;

systemd/openqa-webui.service

@@ -3,6 +3,7 @@ Description=The openQA web UI
 Wants=openqa-setup-db.service openqa-livehandler.service openqa-websockets.service openqa-gru.service openqa-enqueue-asset-cleanup.timer openqa-enqueue-result-cleanup.timer openqa-enqueue-bug-cleanup.timer openqa-minion-restart.path
 After=postgresql.service openqa-setup-db.service nss-lookup.target remote-fs.target apache2.service nginx.service caddy.service
 Before=openqa-gru.service openqa-scheduler.service openqa-livehandler.service
+Documentation=https://open.qa/docs/#_run_the_web_ui
 
 [Service]
 User=geekotest

systemd/openqa-worker-plain@.service

@@ -6,6 +6,7 @@
 Description=openQA Worker #%i
 After=openqa-slirpvde.service network.target nss-lookup.target remote-fs.target time-sync.target
 PartOf=openqa-worker.target
+Documentation=https://open.qa/docs/#_run_openqa_workers
 
 [Service]
 Type=simple