Add manual.

14 files changed, 293 insertions, 0 deletions

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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="gen-refentry-build.xml" />
+  <refsection>
+    <title>Description</title>
+    <para>Convert GFA pangenome file to domagi DuckDB database.</para>
+    <variablelist>
+      <title>Options</title>
+      <varlistentry>
+        <term><option>-g <replaceable>FILE</replaceable></option></term>
+        <term><option>--gfa=<replaceable>FILE</replaceable></option></term>
+        <listitem><para>Input GFAv1 pangenome file</para></listitem>
+      </varlistentry>
+      <xi:include href="output-db-argument.dbk" />
+      <xi:include href="threads-argument.dbk" />
+      <xi:include href="help-option.dbk" />
+    </variablelist>
+  </refsection>
+</refentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+  <xi:include href="gen-refentry-crush.xml" />
+  <refsection>
+    <title>Description</title>
+    <para>Replace runs of Ns with single <literal>N</literal>s (for example, <literal>ANNNT</literal> becomes <literal>ANT</literal>). Similar to <link xlink:href="https://www.ncbi.nlm.nih.gov/genbank/fastaformat/">the FASTA format</link>, the symbol <literal>N</literal> is used to represent ambiguous or unknown nucleotides.</para>
+    <variablelist>
+      <title>Options</title>
+      <xi:include href="input-db-argument.dbk" />
+      <xi:include href="output-db-argument.dbk" />
+      <xi:include href="threads-argument.dbk" />
+      <xi:include href="help-option.dbk" />
+    </variablelist>
+  </refsection>
+</refentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="gen-refentry-depth.xml" />
+  <refsection>
+    <title>Description</title>
+    <para>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.</para>
+    <variablelist>
+      <title>Options</title>
+      <xi:include href="input-db-argument.dbk" />
+      <varlistentry>
+        <term><option>-r <replaceable>PATH</replaceable></option></term>
+        <term><option>--path=<replaceable>PATH</replaceable></option></term>
+        <listitem><para>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.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>-b <replaceable>FILE</replaceable></option></term>
+        <term><option>--bed-input=<replaceable>FILE</replaceable></option></term>
+        <listitem><para>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.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>-d</option></term>
+        <term><option>--graph-depth-table</option></term>
+        <listitem><para>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.</para></listitem>
+      </varlistentry>
+      <xi:include href="threads-argument.dbk" />
+      <xi:include href="help-option.dbk" />
+    </variablelist>
+  </refsection>
+</refentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="gen-refentry-extract.xml" />
+  <refsection>
+    <title>Description</title>
+    <para>Extract subgraphs or parts of a graph defined by query criteria.</para>
+    <variablelist>
+      <title>Options</title>
+      <xi:include href="input-db-argument.dbk" />
+      <xi:include href="output-db-argument.dbk" />
+      <varlistentry>
+        <term><option>-n <replaceable>SEGMENT</replaceable></option></term>
+        <term><option>--node=<replaceable>SEGMENT</replaceable></option></term>
+        <listitem><para>Segment name from which to begin the traversal</para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>-r <replaceable>PATH_RANGE</replaceable></option></term>
+        <term><option>--path-range=<replaceable>PATH_RANGE</replaceable></option></term>
+        <listitem><para>Path range, in <replaceable>path[:pos1[-pos2]]</replaceable> format, from which to begin the traversal</para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>-c <replaceable>STEPS</replaceable></option></term>
+        <term><option>--context-steps=<replaceable>STEPS</replaceable></option></term>
+        <listitem><para>The number of segments away from the initial segments to traverse</para></listitem>
+      </varlistentry>
+      <xi:include href="threads-argument.dbk" />
+      <xi:include href="help-option.dbk" />
+    </variablelist>
+  </refsection>
+</refentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+  <xi:include href="gen-refentry-matrix.xml" />
+  <refsection>
+    <title>Description</title>
+    <para>Write the graph in the <link xlink:href="https://en.wikipedia.org/wiki/Sparse_matrix#Coordinate_list_(COO)">coordinate list</link> sparse matrix format.</para>
+    <variablelist>
+      <title>Options</title>
+      <xi:include href="input-db-argument.dbk" />
+      <xi:include href="threads-argument.dbk" />
+      <xi:include href="help-option.dbk" />
+    </variablelist>
+  </refsection>
+</refentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="gen-refentry-paths.xml" />
+  <refsection>
+    <title>Description</title>
+    <para>Interrogate paths in the pangenome. Nothing is output unless one of the relevant options are specified.</para>
+    <variablelist>
+      <title>Options</title>
+      <xi:include href="input-db-argument.dbk" />
+      <varlistentry>
+        <term><option>-L</option></term>
+        <term><option>--list-paths</option></term>
+        <listitem><para>Print the names of paths in the pangenome, one per line.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><option>-f</option></term>
+        <term><option>--fasta</option></term>
+        <listitem><para>Print paths in FASTA format.</para></listitem>
+      </varlistentry>
+      <xi:include href="threads-argument.dbk" />
+      <xi:include href="help-option.dbk" />
+    </variablelist>
+  </refsection>
+</refentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="gen-refentry-stats.xml" />
+  <refsection>
+    <title>Description</title>
+    <para>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.</para>
+    <variablelist>
+      <title>Options</title>
+      <xi:include href="input-db-argument.dbk" />
+      <varlistentry>
+        <term><option>-S</option></term>
+        <term><option>--summarize</option></term>
+        <listitem><para>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.</para></listitem>
+      </varlistentry>
+      <xi:include href="threads-argument.dbk" />
+      <xi:include href="help-option.dbk" />
+    </variablelist>
+  </refsection>
+</refentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="gen-refentry-view.xml" />
+  <refsection>
+    <title>Description</title>
+    <para>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.</para>
+    <variablelist>
+      <title>Options</title>
+      <xi:include href="input-db-argument.dbk" />
+      <varlistentry>
+        <term><option>-g</option></term>
+        <term><option>--to-gfa</option></term>
+        <listitem><para>Write the pangenome to GFAv1 format.</para></listitem>
+      </varlistentry>
+      <xi:include href="threads-argument.dbk" />
+      <xi:include href="help-option.dbk" />
+    </variablelist>
+  </refsection>
+</refentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<book xmlns="http://docbook.org/ns/docbook"
+      xmlns:xi="http://www.w3.org/2001/XInclude">
+<info>
+  <title>domagi manual</title>
+  <copyright><year>2026</year><holder>Arun Isaac</holder></copyright>
+</info>
+<reference>
+  <title>Reference</title>
+  <xi:include href="domagi-build.dbk" />
+  <xi:include href="domagi-crush.dbk" />
+  <xi:include href="domagi-depth.dbk" />
+  <xi:include href="domagi-extract.dbk" />
+  <xi:include href="domagi-matrix.dbk" />
+  <xi:include href="domagi-paths.dbk" />
+  <xi:include href="domagi-stats.dbk" />
+  <xi:include href="domagi-view.dbk" />
+</reference>
+</book>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<varlistentry xmlns="http://docbook.org/ns/docbook">
+  <term><option>-h</option></term>
+  <term><option>--help</option></term>
+  <listitem><para>Show help message and exit</para></listitem>
+</varlistentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<varlistentry xmlns="http://docbook.org/ns/docbook">
+  <term><option>-i <replaceable>DB</replaceable></option></term>
+  <term><option>--db=<replaceable>DB</replaceable></option></term>
+  <term><option>--idx=<replaceable>DB</replaceable></option></term>
+  <listitem><para>Input pangenome DuckDB database</para></listitem>
+</varlistentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<varlistentry xmlns="http://docbook.org/ns/docbook">
+  <term><option>-o <replaceable>DB</replaceable></option></term>
+  <term><option>--out=<replaceable>DB</replaceable></option></term>
+  <listitem><para>Output pangenome DuckDB database</para></listitem>
+</varlistentry>
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 @@
+<?xml version="1.0" encoding="utf-8"?>
+<varlistentry xmlns="http://docbook.org/ns/docbook">
+  <term><option>-t <replaceable>THREADS</replaceable></option></term>
+  <term><option>--threads=<replaceable>THREADS</replaceable></option></term>
+  <listitem><para>Number of threads. If unspecified, all available CPUs are used.</para></listitem>
+</varlistentry>
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)