sphinx docs, closes #11

docs/API.rst

@@ -0,0 +1,29 @@
+API
+===
+
+vcf.Reader
+----------
+
+.. autoclass:: vcf.Reader
+   :members:
+
+vcf.Writer
+----------
+
+.. autoclass:: vcf.Writer
+   :members:
+
+vcf._Record
+-----------
+
+.. autoclass:: vcf._Record
+   :members:
+
+vcf._Call
+---------
+
+.. autoclass:: vcf._Call
+   :members:
+
+
+

docs/FILTERS.rst

@@ -0,0 +1,90 @@
+Filtering VCF files
+===================
+
+The filter script: vcf_filter.py
+--------------------------------
+
+Filtering a VCF file based on some properties of interest is a common enough 
+operation that PyVCF offers an extensible script.  ``vcf_filter.py`` does 
+the work of reading input, updating the metadata and filtering the records.
+
+
+Adding a filter
+---------------
+
+You can reuse this work by providing a filter class, rather than writing your own filter.
+For example, lets say I want to filter each site based on the quality of the site.
+I can create a class like this::
+    
+    class SiteQuality(vcf.Filter):
+
+        description = 'Filter sites by quality'
+        name = 'sq'
+
+        @classmethod
+        def customize_parser(self, parser):
+            parser.add_argument('--site-quality', type=int, default=30,
+                    help='Filter sites below this quality')
+
+        def __init__(self, args):
+            self.threshold = args.site_quality
+
+        def __call__(self, record):
+            if record.QUAL < self.threshold:
+                return record.QUAL
+
+
+This class subclasses ``vcf.Filter`` which provides the interface for VCF filters.
+The ``description``` and ``name`` are metadata about the parser.
+The ``customize_parser`` method allows you to add arguments to the script.
+We use the ``__init__`` method to grab the argument of interest from the parser.
+Finally, the ``__call__`` method processes each record and returns a value if the 
+filter failed.  The base class uses the ``name`` and ``threshold`` to create
+the filter ID in the VCF file.
+
+To make vcf_filter.py aware of the filter, you need to declare a ``vcf.filters`` entry 
+point in your ``setup``::
+
+    setup(
+        ...
+        entry_points = {
+            'vcf.filters': [
+                'site_quality = module.path:SiteQuality',
+            ]
+        }
+    )
+
+Now when you call vcf_filter.py, you should see your filter in the list of available filters::
+
+    >$ vcf_filter.py --help
+    usage: vcf_filter.py [-h] [--no-short-circuit] [--output OUTPUT]
+                         [--site-quality SITE_QUALITY]
+                         [--genotype-quality GENOTYPE_QUALITY]
+                         input filter [filter ...]
+
+    Filter a VCF file
+
+    available filters:
+      sq:	Filter sites by quality
+
+    positional arguments:
+      input                 File to process (use - for STDIN)
+      filter                Filters to use
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --no-short-circuit    Do not stop filter processing on a site if a single
+                            filter fails.
+      --output OUTPUT       Filename to output (default stdout)
+      --site-quality SITE_QUALITY
+                            Filter sites below this quality
+      --genotype-quality GENOTYPE_QUALITY
+                            Filter sites with no genotypes above this quality
+
+
+The filter base class: vcf.Filter
+---------------------------------
+
+.. autoclass:: vcf.Filter
+   :members:
+

HISTORY.md → docs/HISTORY.rst

@@ -1,3 +1,16 @@
+Changes
+=======
+
+0.2.2 Release
+-------------
+
+Documentation release
+
+0.2.1 Release
+-------------
+
+* Add shebang to vcf_filter.py
+
 0.2 Release 
 -----------
 
@@ -23,3 +36,4 @@ Contributions
 
 Project started by @jdoughertyii and taken over by @jamescasbon on 12th January 2011.
 
+

docs/INTRO.rst

@@ -0,0 +1,5 @@
+Introduction
+============
+
+.. automodule:: vcf
+

docs/Makefile

@@ -0,0 +1,130 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PyVCF.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PyVCF.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/PyVCF"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PyVCF"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

docs/_build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 0496c9ff433665d411ac1e8d2fa80c8b
+tags: fbb0d17656682115ca4d033fb2f83ba1