+ document how to run bcftools commands from pysam

  - this wasn't explicitly stated in the documentation.  I was
    using the notes described in [github issue 958][0] as a guide.

[0]: pysam-developers#958

doc/usage.rst

@@ -172,6 +172,25 @@ Note that this means that output from commands which produce output on
 stdout will not be available. The only solution is to run samtools
 commands through subprocess.
 
+=====================================
+Using bcftools commands within python
+=====================================
+
+Commands available in `bcftools`_ are also available as simple
+function calls, but they are invoked slightly differently from `samtools`_.
+Command line options are also provided as arguments. For
+example::
+
+   import pysam.bcftools as bcftools
+   bcftools.reheader("-s", "samples.txt", "-o", "out.vcf.gz", "in.vcf.gz", catch_stdout=False)
+
+corresponds to the command line::
+
+   bcftools reheader -s samples.txt -o out.vcf.gz in.vcf.gz
+
+If the `catch_stdout=False`_ option is not specified, then the output of the
+`bcftools`_ command will be returned as a variable
+
 ================================
 Working with tabix-indexed files
 ================================