[DOCS] new docs for bamtofastq

docs/content/tools/bamtofastq.rst

 ###############
 *bamtofastq*
-###############
\ No newline at end of file
+###############
+``bedtools bamtofastq`` is a conversion utility for extracting FASTQ records
+from sequence alignments in BAM format. 
+
+==========================================================================
+Usage and option summary
+==========================================================================
+**Usage**:
+::
+
+    bedtools bamtofastq [OPTIONS] -i <BAM> -fq <FASTQ>
+
+**(or)**:
+::
+
+    bamToFastq [OPTIONS] -i <BAM> -fq <FASTQ>
+
+
+
+.. tabularcolumns:: |p{4.5cm}|p{8.5cm}|
+
+=============   ================================================================
+Option          Description
+=============   ================================================================
+**-fq2**        FASTQ for second end.  Used if BAM contains paired-end data.
+                BAM should be sorted by query name 
+                (``samtools sort -n aln.bam aln.qsort``) if creating 
+                paired FASTQ with this option.
+**-tags**       Create FASTQ based on the mate info in the BAM R2 and Q2 tags.
+=============   ================================================================
+
+
+==========================================================================
+Default behavior
+==========================================================================
+By default, each alignment in the BAM file is converted to a FASTQ record
+in the ``-fq`` file. The order of the records in the resulting FASTQ exactly
+follows the order of the records in the BAM input file.
+
+.. code-block:: bash
+
+  $ bedtools bamtofastq -i NA18152.bam -fq NA18152.fq
+  
+  $ head -8 NA18152.fq
+  @NA18152-SRR007381.35051
+  GGAGACATATCATATAAGTAATGCTAGGGTGAGTGGTAGGAAGTTTTTTCATAGGAGGTGTATGAGTTGGTCGTAGCGGAATCGGGGGTATGCTGTTCGAATTCATAAGAACAGGGAGGTTAGAAGTAGGGTCTTGGTGACAAAATATGTTGTATAGAGTTCAGGGGAGAGTGCGTCATATGTTGTTCCTAGGAAGATTGTAGTGGTGAGGGTGTTTATTATAATAATGTTTGTGTATTCGGCTATGAAGAATAGGGCGAAGGGGCCTGCGGCGTATTCGATGTTGAAGCCTGAGACTAGTTCGGACTCCCCTTCGGCAAGGTCGAA
+  +
+  <<<;;<;<;;<;;;;;;;;;;;;<<<:;;;;;;;;;;;;;;;;::::::;;;;<<;;;;;;;;;;;;;;;;;;;;;;;;;;;;<<<<<;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;<<;;;;;:;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;<<<;;;;;;;;;;<<<<<<<<;;;;;;;;;:;;;;;;;;;;;;;;;;;;;:;;;;8;;8888;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8966689666666299866669:899
+  @NA18152-SRR007381.637219
+  AATGCTAGGGTGAGTGGTAGGAAGTTTTTTCATAGGAGGTGTATGAGTTGGTCGTAGCGGAATCGGGGGTATGCTGTTCGAATTCATAAGAACAGGGAGGTTAGAAGTAGGGTCTTGGTGACAAAATATGTTGTATAGAGTTCAGGGGAGAGTGCGTCATATGTTGTTCCTAGGAAGATTGTAGTGGTGAGGGTGTTTATTATAATAATGTTTGTGTATTCGGCTATGAAGAATAGGGCGAAGGGGCCTGCGGCGTATTCGATGTTGAAGCCTGAGACTAGTTCGGACTCCCCTTCCGGCAAGGTCGAA
+  +
+  <<<<<<<<<<;;<;<;;;;<<;<888888899<;;;;;;<;;;;;;;;;;;;;;;;;;;;;;;;<<<<<;;;;;;;;;<;<<<<<;;;;;;;;;;;;;<<<<;;;;;;;:::;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;<<<<;;;;;;;;;;;;;;;;;;;;;;;<;;;;;;;;;;;;;;;;;;;;;;<888<;<<;;;;<<<<<<;;;;;<<<<<<<<;;;;;;;;;:;;;;888888899:::;;8;;;;;;;;;;;;;;;;;;;99;;99666896666966666600;96666669966
+
+
+
+==========================================================================
+``-fq2`` Creating two FASTQ files for paired-end sequences.
+==========================================================================
+If your BAM alignments are from paired-end sequence data, one can use the
+``-fq2`` option to create two distinct FASTQ output files --- one for 
+end 1 and one for end 2.
+
+.. note::
+
+    When using this option, it is required that the BAM 
+    file is sorted/grouped by the read name. This keeps the resulting records
+    in the two output FASTQ files in the same order. One can sort the BAM
+    file by query name with ``samtools sort -n aln.bam aln.qsort``.
+
+
+.. code-block:: bash
+
+  $ samtools sort -n aln.bam aln.qsort
+  
+  $ bedtools bamtofastq -i aln.qsort.bam \
+                        -fq aln.end1.fq \
+                        -fq2 aln.end2.fq
+                        
+  $ head -8 aln.end1.fq
+  @SRR069529.2276/1
+  CAGGGAGAAGGAGGTAGGAAAGAGAAAGGACCAGGGAGGGGCGCATACACAGGACGCTCCGTGCGGTGATAGCAGCACCACACTGTGTTCAGTCGTCTGGC
+  +
+  =;@>==###############################################################################################
+  @SRR069529.2406/1
+  GCTGGGAAAAGGATTCAGGATGTTGGTTTCTATCTTTGAGTTGCTGCTGTGCGGCTGTCCCTACACTCGCAGTACCCCTCGGACACCGTCTACTGTGGAGG
+  +
+  =5@><<:?<?
+  
+  $ head -8 aln.end2.fq
+  @SRR069529.2276/2
+  AGACCCAGAGAGGGACAGGATCTGTCCCAGATCATAAAATAGGGGGAGTGCTCCGTAGAGGCGTGCGCGGTGGCACCGTGCAGTAGTACGGGTGAGCGGGG
+  +
+  #####################################################################################################
+  @SRR069529.2406/2
+  TTCCCTACCCCTGGGGTCAGGGACTACAGCCAAGGGGAGAACTTTAGCAAGTAGACGTTAGTTATTTTGATTCCAGTGGGGACGCGCGTGTAGCGAGTTGT
+  +
+  @>=AABB?AAACABBA>@?AAAA>B@@AB@AA:B@AA@??#############################################################
+
+