From a86ef4eda927c47791dc0c25852c13ea622f809b Mon Sep 17 00:00:00 2001
From: Justin Bedo <cu@cua0.org>
Date: Wed, 6 Mar 2019 11:43:19 +1100
Subject: draft API docs for BWA and strelka

---
 doc/tools-doc.nix | 41 +++++++++++++++++++++++++++++++++++++++++
 doc/tools.xml     | 14 ++++++++++++++
 tools/bwa.nix     | 13 +++++++++++--
 tools/strelka.nix | 27 ++++++++++++++++++++++++---
 4 files changed, 90 insertions(+), 5 deletions(-)
 create mode 100644 doc/tools-doc.nix
 create mode 100644 doc/tools.xml

diff --git a/doc/tools-doc.nix b/doc/tools-doc.nix
new file mode 100644
index 0000000..b2cd7ba
--- /dev/null
+++ b/doc/tools-doc.nix
@@ -0,0 +1,41 @@
+{ bionix ? import ./.. {} }:
+
+with bionix;
+
+stage {
+  name = "tools-docs";
+  src = ../tools;
+
+  xsltFlags = lib.concatStringsSep " " [
+    #"--param section.autolabel 1"
+    #"--param section.label.includes.component.label 1"
+    #"--stringparam html.stylesheet 'style.css overrides.css highlightjs/mono-blue.css'"
+    #"--stringparam html.script './highlightjs/highlight.pack.js ./highlightjs/loader.js'"
+    #"--param xref.with.number.and.title 1"
+    #"--param toc.section.depth 3"
+    #"--stringparam admon.style ''"
+    #"--stringparam callout.graphics.extension .svg"
+  ];
+
+
+  buildInputs = with pkgs; [ nixdoc libxslt libxml2 ];
+  installPhase = ''
+    function docgen {
+      nixdoc -c "$1" -d "$2" -f "$1.nix" | sed 's/lib\./bionix./g' |grep -v locations.xml > "$1.xml"
+    }
+
+    docgen bwa 'BWA aligner'
+    docgen strelka 'Strelka2 variant caller'
+
+    mkdir $out
+    cp ${./tools.xml} tools.xml
+    xmllint --nonet --xinclude --noxincludenode tools.xml --output tools-full.xml
+    cat tools-full.xml
+    xsltproc $xsltFlags \
+      --nonet \
+      --xinclude \
+      --output $out/index.html \
+      ${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
+      tools-full.xml
+  '';
+}
diff --git a/doc/tools.xml b/doc/tools.xml
new file mode 100644
index 0000000..f23dfeb
--- /dev/null
+++ b/doc/tools.xml
@@ -0,0 +1,14 @@
+<book xmlns="http://docbook.org/ns/docbook"
+      xmlns:xi="http://www.w3.org/2001/XInclude">
+ <info>
+  <title>Bionix</title>
+ </info>
+ <section xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xml:id="sec-tools">
+  <title>Tools</title>
+  <xi:include href="bwa.xml" />
+  <xi:include href="strelka.xml" />
+ </section>
+</book>
diff --git a/tools/bwa.nix b/tools/bwa.nix
index d0ab5ee..03735d1 100644
--- a/tools/bwa.nix
+++ b/tools/bwa.nix
@@ -2,7 +2,16 @@
 
 with bionix;
 
-{
-  align = callBionixE ./bwa-mem.nix;
+rec {
+  /* Align read against a reference: defaults to bwa-mem */
+  align = bwa-mem;
+
+  /* Align reads against a reference using bwa-mem
+  Type: bwa-mem :: {ref = fasta, bamOutput = bool, ...} -> {input1, input2} -> bam/sam
+  */
+  bwa-mem = callBionixE ./bwa-mem.nix;
+  /* Creates an reference index for BWA
+  Type: {...} -> fasta -> BWA index
+  */
   index = callBionixE ./bwa-index.nix;
 }
diff --git a/tools/strelka.nix b/tools/strelka.nix
index 9a8f1aa..1cf8961 100644
--- a/tools/strelka.nix
+++ b/tools/strelka.nix
@@ -4,21 +4,42 @@ with bionix;
 with types;
 
 {
+  /* Calls somatic variants
+  Type: callSomatic :: {...} -> {tumour, normal} -> somatic results
+  */
   callSomatic = callBionixE ./strelka-callSomatic.nix;
+  /* Calls variants
+  Type: call :: {...} -> [input] -> results
+  */
   call = callBionixE ./strelka-call.nix;
-  variants = drv: stage {
+  /* Extract VCF file from results
+  Type: variants :: results -> vcf
+  */
+  variants =
+    # result of call
+    drv: stage {
     name = "strelka-call-variants";
     buildCommand = ''
       ln -s ${drv}/variants/variants.vcf.gz $out
     '';
     passthru.filetype = filetype.gz (filetype.vcf {ref=ref;});
   };
-  indels = drv: stage {
+  /* Extract indels from somatic results
+  Type: indels :: somatic results -> vcf
+  */
+  indels =
+    # result of callSomatic
+    drv: stage {
     name = "strelka-callVariants-indels";
     buildCommand = "ln -s ${drv}/variants/somatic.indels.vcf.gz $out";
     passthru.filetype = filetype.gz (filetype.vcf {ref = ref;});
   };
-  snvs = drv: stage {
+  /* Extract SNVs from somatic results
+  Type: snvs :: somatic results -> vcf
+  */
+  snvs =
+    # result of callSomatic
+    drv: stage {
     name = "strelka-callVariants-snvs";
     buildCommand = "ln -s ${drv}/variants/somatic.snvs.vcf.gz $out";
     passthru.filetype = filetype.gz (filetype.vcf {ref = ref;});
-- 
cgit v1.2.3