From 439ada732261b76816dddc236ee41cca651a0c14 Mon Sep 17 00:00:00 2001
From: Arun Isaac
Date: Thu, 13 Aug 2026 22:13:01 +0100
Subject: Add manual.
---
doc/domagi-build.dbk | 20 +++++++++++++
doc/domagi-crush.dbk | 17 +++++++++++
doc/domagi-depth.dbk | 30 ++++++++++++++++++++
doc/domagi-extract.dbk | 31 ++++++++++++++++++++
doc/domagi-matrix.dbk | 16 +++++++++++
doc/domagi-paths.dbk | 25 +++++++++++++++++
doc/domagi-stats.dbk | 20 +++++++++++++
doc/domagi-view.dbk | 20 +++++++++++++
doc/domagi.dbk | 19 +++++++++++++
doc/help-option.dbk | 6 ++++
doc/input-db-argument.dbk | 7 +++++
doc/output-db-argument.dbk | 6 ++++
doc/threads-argument.dbk | 6 ++++
extractdoc.py | 70 ++++++++++++++++++++++++++++++++++++++++++++++
14 files changed, 293 insertions(+)
create mode 100644 doc/domagi-build.dbk
create mode 100644 doc/domagi-crush.dbk
create mode 100644 doc/domagi-depth.dbk
create mode 100644 doc/domagi-extract.dbk
create mode 100644 doc/domagi-matrix.dbk
create mode 100644 doc/domagi-paths.dbk
create mode 100644 doc/domagi-stats.dbk
create mode 100644 doc/domagi-view.dbk
create mode 100644 doc/domagi.dbk
create mode 100644 doc/help-option.dbk
create mode 100644 doc/input-db-argument.dbk
create mode 100644 doc/output-db-argument.dbk
create mode 100644 doc/threads-argument.dbk
create mode 100644 extractdoc.py
diff --git a/doc/domagi-build.dbk b/doc/domagi-build.dbk
new file mode 100644
index 0000000..1501416
--- /dev/null
+++ b/doc/domagi-build.dbk
@@ -0,0 +1,20 @@
+
+
+
+
+ Description
+ Convert GFA pangenome file to domagi DuckDB database.
+
+ Options
+
+
+
+ Input GFAv1 pangenome file
+
+
+
+
+
+
+
diff --git a/doc/domagi-crush.dbk b/doc/domagi-crush.dbk
new file mode 100644
index 0000000..db958bb
--- /dev/null
+++ b/doc/domagi-crush.dbk
@@ -0,0 +1,17 @@
+
+
+
+
+ Description
+ Replace runs of Ns with single Ns (for example, ANNNT becomes ANT). Similar to the FASTA format, the symbol N is used to represent ambiguous or unknown nucleotides.
+
+ Options
+
+
+
+
+
+
+
diff --git a/doc/domagi-depth.dbk b/doc/domagi-depth.dbk
new file mode 100644
index 0000000..48405f2
--- /dev/null
+++ b/doc/domagi-depth.dbk
@@ -0,0 +1,30 @@
+
+
+
+
+ Description
+ Find the depth of a graph as defined by query criteria. The depth of each segment is defined as the number of paths that run through that segment. When invoked without any options, the mean depth of each path is printed in a four-column tab-delimited format with the following columns—path, start coordinate, end coordinate and mean depth. The mean depth of a path is the mean of the depth of all segments in that path with each depth weighted by the length of that segment.
+
+ Options
+
+
+
+
+ Only compute the mean depth of the specified path. This argument may be specified more than once to compute the mean depth of more than one path.
+
+
+
+
+ BED file specifying ranges over paths of the graph. When this option is specified, compute the mean depth of these ranges rather than the mean depth of the paths.
+
+
+
+
+ Print the depth and unique depth of each segment in the graph. The unique depth of a segment is the number of distinct paths that run through that segment. The output is printed in a three-column tab-delimited format with the following columns—segment name, depth and unique depth.
+
+
+
+
+
+
diff --git a/doc/domagi-extract.dbk b/doc/domagi-extract.dbk
new file mode 100644
index 0000000..a2b7c6b
--- /dev/null
+++ b/doc/domagi-extract.dbk
@@ -0,0 +1,31 @@
+
+
+
+
+ Description
+ Extract subgraphs or parts of a graph defined by query criteria.
+
+ Options
+
+
+
+
+
+ Segment name from which to begin the traversal
+
+
+
+
+ Path range, in path[:pos1[-pos2]] format, from which to begin the traversal
+
+
+
+
+ The number of segments away from the initial segments to traverse
+
+
+
+
+
+
diff --git a/doc/domagi-matrix.dbk b/doc/domagi-matrix.dbk
new file mode 100644
index 0000000..9b8dea0
--- /dev/null
+++ b/doc/domagi-matrix.dbk
@@ -0,0 +1,16 @@
+
+
+
+
+ Description
+ Write the graph in the coordinate list sparse matrix format.
+
+ Options
+
+
+
+
+
+
diff --git a/doc/domagi-paths.dbk b/doc/domagi-paths.dbk
new file mode 100644
index 0000000..ed83ee7
--- /dev/null
+++ b/doc/domagi-paths.dbk
@@ -0,0 +1,25 @@
+
+
+
+
+ Description
+ Interrogate paths in the pangenome. Nothing is output unless one of the relevant options are specified.
+
+ Options
+
+
+
+
+ Print the names of paths in the pangenome, one per line.
+
+
+
+
+ Print paths in FASTA format.
+
+
+
+
+
+
diff --git a/doc/domagi-stats.dbk b/doc/domagi-stats.dbk
new file mode 100644
index 0000000..5b9d620
--- /dev/null
+++ b/doc/domagi-stats.dbk
@@ -0,0 +1,20 @@
+
+
+
+
+ Description
+ Compute variation graph statistics. Among other metrics, it can compute the number nodes, the number of edges, the number of paths and the total nucleotide length of the graph.
+
+ Options
+
+
+
+
+ Summarize the graph properties. Output is printed in a five-column tab-delimited format with the following columns—the number of nucleotides, the number of segments, the number of links, the number of paths, and the number of steps. The number of nucleotides is the total number across all segments of the graph. The number of steps is the total number of segments traversed by all paths in the pangenome. Segments that are traversed more than once are counted multiple times.
+
+
+
+
+
+
diff --git a/doc/domagi-view.dbk b/doc/domagi-view.dbk
new file mode 100644
index 0000000..19bf681
--- /dev/null
+++ b/doc/domagi-view.dbk
@@ -0,0 +1,20 @@
+
+
+
+
+ Description
+ Convert a pangenome in domagi DuckDB database format to other formats. Only GFAv1 is supported at the moment. Nothing is output unless one of the relevant options are specified.
+
+ Options
+
+
+
+
+ Write the pangenome to GFAv1 format.
+
+
+
+
+
+
diff --git a/doc/domagi.dbk b/doc/domagi.dbk
new file mode 100644
index 0000000..0079fa2
--- /dev/null
+++ b/doc/domagi.dbk
@@ -0,0 +1,19 @@
+
+
+
+ domagi manual
+ 2026Arun Isaac
+
+
+ Reference
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/help-option.dbk b/doc/help-option.dbk
new file mode 100644
index 0000000..6a62a49
--- /dev/null
+++ b/doc/help-option.dbk
@@ -0,0 +1,6 @@
+
+
+
+
+ Show help message and exit
+
diff --git a/doc/input-db-argument.dbk b/doc/input-db-argument.dbk
new file mode 100644
index 0000000..5613676
--- /dev/null
+++ b/doc/input-db-argument.dbk
@@ -0,0 +1,7 @@
+
+
+
+
+
+ Input pangenome DuckDB database
+
diff --git a/doc/output-db-argument.dbk b/doc/output-db-argument.dbk
new file mode 100644
index 0000000..9cb3336
--- /dev/null
+++ b/doc/output-db-argument.dbk
@@ -0,0 +1,6 @@
+
+
+
+
+ Output pangenome DuckDB database
+
diff --git a/doc/threads-argument.dbk b/doc/threads-argument.dbk
new file mode 100644
index 0000000..1b5de83
--- /dev/null
+++ b/doc/threads-argument.dbk
@@ -0,0 +1,6 @@
+
+
+
+
+ Number of threads. If unspecified, all available CPUs are used.
+
diff --git a/extractdoc.py b/extractdoc.py
new file mode 100644
index 0000000..14cfb94
--- /dev/null
+++ b/extractdoc.py
@@ -0,0 +1,70 @@
+from collections import namedtuple
+from lxml import etree
+from lxml.builder import E
+import sys
+
+from domagi.domagi import main
+import click
+
+Command = namedtuple("Command", "name options short_help")
+
+namespaces = {"dbk": "http://docbook.org/ns/docbook"}
+
+def printtree(tree, file):
+ print(etree.tostring(tree).decode(), file=file)
+
+def clickfunc2commands(func):
+ with click.Context(func) as ctx:
+ info = ctx.to_info_dict()
+ return [Command(name,
+ (frozenset({tuple(parameter["opts"])
+ for parameter in properties["params"]})
+ # We add the -h variant of the help option to all
+ # subcommands through the context settings. This does not
+ # reflect properly in the info dict. Hence this hack to add
+ # it back.
+ | frozenset({("-h", "--help")}))
+ - frozenset({("--help",)}),
+ properties["short_help"])
+ for name, properties in info["command"]["commands"].items()]
+
+def refentry2options(refentry):
+ name, = refentry.xpath("dbk:refnamediv/dbk:refname/text()",
+ namespaces=namespaces)
+ return (name.removeprefix("domagi-"),
+ frozenset({tuple(option.rstrip("= ")
+ for option in varlistentry.xpath("dbk:term/dbk:option/text()",
+ namespaces=namespaces))
+ for varlistentry
+ in refentry.xpath("dbk:refsection/dbk:variablelist[dbk:title='Options']//dbk:varlistentry",
+ namespaces=namespaces)}))
+
+subcommands = clickfunc2commands(main)
+
+# Extract information about subcommands from the source to add to the
+# documentation.
+for subcommand in subcommands:
+ with open(f"doc/gen-refentry-{subcommand.name}.xml", "w") as file:
+ printtree(E.refnamediv(E.refname(f"domagi-{subcommand.name}"),
+ E.refpurpose(subcommand.short_help),
+ xmlns="http://docbook.org/ns/docbook"),
+ file)
+
+# Validate documented subcommands. TODO: Also check if the metasyntactic
+# variables for the arguments match.
+with open("doc/domagi.dbk") as f:
+ tree = etree.parse(f)
+ tree.xinclude()
+documented = dict([refentry2options(refentry)
+ for refentry in tree.xpath("//dbk:refentry", namespaces=namespaces)])
+for subcommand in subcommands:
+ if subcommand.name not in documented:
+ sys.exit(f"Undocumented subcommand: {subcommand.name}")
+ undocumented_options = subcommand.options - documented[subcommand.name]
+ unknown_options = documented[subcommand.name] - subcommand.options
+ if undocumented_options or unknown_options:
+ if undocumented_options:
+ print(f"Undocumented fields {list(undocumented_options)} in {subcommand.name} documentation")
+ if unknown_options:
+ print(f"Unknown option {list(unknown_options)} in {subcommand.name} documentation")
+ sys.exit(1)
--
cgit 1.4.1