Permalink
Browse files

sphinx docs, closes #11

  • Loading branch information...
1 parent 5400def commit 566f76cb2fcd59bca867ba051ff03bff695433fe James Casbon committed Jan 25, 2012
Showing with 5,218 additions and 64 deletions.
  1. BIN docs/.DS_Store
  2. +29 −0 docs/API.rst
  3. +90 −0 docs/FILTERS.rst
  4. +14 −0 HISTORY.md → docs/HISTORY.rst
  5. +5 −0 docs/INTRO.rst
  6. +130 −0 docs/Makefile
  7. BIN docs/_build/doctrees/API.doctree
  8. BIN docs/_build/doctrees/FILTERS.doctree
  9. BIN docs/_build/doctrees/HISTORY.doctree
  10. BIN docs/_build/doctrees/INTRO.doctree
  11. BIN docs/_build/doctrees/environment.pickle
  12. BIN docs/_build/doctrees/index.doctree
  13. +4 −0 docs/_build/html/.buildinfo
  14. +354 −0 docs/_build/html/API.html
  15. +234 −0 docs/_build/html/FILTERS.html
  16. +153 −0 docs/_build/html/HISTORY.html
  17. +253 −0 docs/_build/html/INTRO.html
  18. +89 −0 docs/_build/html/_modules/index.html
  19. +894 −0 docs/_build/html/_modules/vcf.html
  20. +29 −0 docs/_build/html/_sources/API.txt
  21. +21 −7 FILTERS.md → docs/_build/html/_sources/FILTERS.txt
  22. +39 −0 docs/_build/html/_sources/HISTORY.txt
  23. +5 −0 docs/_build/html/_sources/INTRO.txt
  24. +21 −0 docs/_build/html/_sources/index.txt
  25. +528 −0 docs/_build/html/_static/basic.css
  26. +256 −0 docs/_build/html/_static/default.css
  27. +247 −0 docs/_build/html/_static/doctools.js
  28. BIN docs/_build/html/_static/file.png
  29. +154 −0 docs/_build/html/_static/jquery.js
  30. BIN docs/_build/html/_static/minus.png
  31. BIN docs/_build/html/_static/plus.png
  32. +62 −0 docs/_build/html/_static/pygments.css
  33. +518 −0 docs/_build/html/_static/searchtools.js
  34. +148 −0 docs/_build/html/_static/sidebar.js
  35. +16 −0 docs/_build/html/_static/underscore.js
  36. +237 −0 docs/_build/html/genindex.html
  37. +148 −0 docs/_build/html/index.html
  38. BIN docs/_build/html/objects.inv
  39. +111 −0 docs/_build/html/py-modindex.html
  40. +102 −0 docs/_build/html/search.html
  41. +1 −0 docs/_build/html/searchindex.js
  42. +216 −0 docs/conf.py
  43. +21 −0 docs/index.rst
  44. +1 −1 setup.py
  45. +13 −7 test/test_vcf.py
  46. +73 −44 vcf.py
  47. +2 −5 vcf_filter.py
View
Binary file not shown.
View
@@ -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:
+
+
+
View
@@ -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:
+
@@ -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.
+
View
@@ -0,0 +1,5 @@
+Introduction
+============
+
+.. automodule:: vcf
+
View
@@ -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."
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -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
Oops, something went wrong.

0 comments on commit 566f76c

Please sign in to comment.