Merge pull request #191 from jeromekelleher/some-docs

Some docs infrastructure

Author: jeromekelleher

docs/_config.yml

@@ -10,15 +10,6 @@ logo: logo.png
 execute:
   execute_notebooks: force
 
-# Define the name of the latex output file for PDF builds
-latex:
-  latex_documents:
-    targetname: bio2zarr.tex
-
-# Add a bibtex file so that we can create citations
-bibtex_bibfiles:
-  - references.bib
-
 # Information about where the book exists on the web
 repository:
   url: https://github.com/sgkit-dev/bio2zarr  # Online location of your book
@@ -33,4 +24,4 @@ html:
 
 sphinx:
   extra_extensions:
-    - sphinx_click.ext
+    - sphinx_click.ext

docs/_static/custom.css

@@ -0,0 +1,5 @@
+.bd-sidebar-primary div#rtd-footer-container {
+  bottom:-1rem;
+  margin:-1rem;
+  position:fixed;
+}

docs/cli.md

@@ -1,10 +1,77 @@
 # Command Line Interface
 
+% A note on cross references... There's some weird long-standing problem with 
+% cross referencing program values in Sphinx, which means that we can't use
+% the built-in labels generated by sphinx-click. We can make our own explicit
+% targets, but these have to have slightly weird names to avoid conflicting
+% with what sphinx-click is doing. So, hence the cmd- prefix.
+% Based on: https://github.com/skypilot-org/skypilot/pull/2834
+
 ```{eval-rst}
+.. _cmd-vcf2zarr:
 .. click:: bio2zarr.cli:vcf2zarr
-   :prog: vcf2zarr
-   :show-nested:
+   :prog: vcf2zarr 
+   :nested: short
+
+.. _cmd-vcf2zarr-convert:
+.. click:: bio2zarr.cli:convert_vcf
+   :prog: vcf2zarr convert
+   :nested: full
+
+.. _cmd-vcf2zarr-inspect:
+.. click:: bio2zarr.cli:inspect
+   :prog: vcf2zarr inspect
+   :nested: full
+
+.. _cmd-vcf2zarr-mkschema:
+.. click:: bio2zarr.cli:mkschema
+   :prog: vcf2zarr mkschema
+   :nested: full
+```
+
+## Explode
+
+```{eval-rst}
+.. click:: bio2zarr.cli:explode
+   :prog: vcf2zarr explode
+   :nested: full
+
+.. _cmd-vcf2zarr-dexplode-init:
+.. click:: bio2zarr.cli:dexplode_init
+   :prog: vcf2zarr dexplode-init
+   :nested: full
+
+.. _cmd-vcf2zarr-dexplode-partition:
+.. click:: bio2zarr.cli:dexplode_partition
+   :prog: vcf2zarr dexplode-partition
+   :nested: full
+
+.. _cmd-vcf2zarr-dexplode-finalise:
+.. click:: bio2zarr.cli:dexplode_finalise
+   :prog: vcf2zarr dexplode-finalise
+   :nested: full
+```
+
+## Encode
+
+```{eval-rst}
+.. click:: bio2zarr.cli:encode
+   :prog: vcf2zarr encode
+   :nested: full
+
+.. _cmd-vcf2zarr-dencode-init:
+.. click:: bio2zarr.cli:dencode_init
+   :prog: vcf2zarr dencode-init
+   :nested: full
+
+.. _cmd-vcf2zarr-dencode-partition:
+.. click:: bio2zarr.cli:dencode_partition
+   :prog: vcf2zarr dencode-partition
+   :nested: full
+
+.. _cmd-vcf2zarr-dencode-finalise:
+.. click:: bio2zarr.cli:dencode_finalise
+   :prog: vcf2zarr dencode-finalise
+   :nested: full
+```
 
-.. click:: bio2zarr.cli:plink2zarr
-   :prog: plink2zarr
-   :show-nested:

docs/intro.md

@@ -31,7 +31,7 @@ and will always work.
 
 ## Basic vcf2zarr usage
 For modest VCF files (up to a few GB), a single command can be used to convert a VCF file
-(or set of VCF files) to Zarr:
+(or set of VCF files) using the {ref}`convert<cmd-vcf2zarr-convert>` command:
 
 ```bash
 $ vcf2zarr convert <VCF1> <VCF2> ... <VCFN> <zarr>

docs/references.bib

@@ -42,7 +42,7 @@ dynamic = ["version"]
 
 [project.urls]
 repository = "https://github.com/sgkit-dev/bio2zarr"
-documentation = "https://sgkit-dev.github.io/bio2zarr/intro.html"
+documentation = "https://sgkit-dev.github.io/bio2zarr/"
 
 [project.scripts]
 vcf2zarr = "bio2zarr.cli:vcf2zarr"