DOC Document backwards compatibility fixes

Author: luispedro

docs/sources/backwards.md

@@ -0,0 +1,35 @@
+# List of backwards compatibility fixes
+
+As NGLess uses a version declaration string at the top of script means that
+NGLess can change its behaviour depending on the version used in the script.
+
+## < NGLess 1.1
+
+- The way that CIGAR sequence lengths are computed has changed to match
+  samtools. This implies that the computation of `min_match_size` and
+  `min_identity_pc` have slightly changed.
+
+## < NGLess 0.8
+
+- Select changes how a corner case is handled.
+
+## < NGLess 0.6
+
+- The `count` function now defaults to `include_minus1` being true.
+
+## < NGLess 0.5
+
+- The `preprocess` function now modifies its argument. Older code using
+
+```python
+preprocess(input) using |r|:
+    ...
+```
+is automatically treated as:
+
+
+```python
+input = preprocess(input) using |r|:
+    ...
+```
+

docs/sources/conf.py

@@ -45,8 +45,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'ngless'
-copyright = u'2013-2018, NGLess Authors'
+project = u'NGLess'
+copyright = u'2013-2019, NGLess Authors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -234,7 +234,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'ngless', u'ngless Documentation',
+    ('index', 'NGLess', u'NGLess Documentation',
      [u'NGLess Authors'], 1)
 ]
 
@@ -248,8 +248,8 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'ngless', u'ngless Documentation',
-   u'NGLess Authors', 'ngless', 'One line description of project.',
+  ('index', 'NGLess', u'NGLess Documentation',
+   u'NGLess Authors', 'NGLess', 'One line description of project.',
    'Miscellaneous'),
 ]
 

docs/sources/index.rst

@@ -18,14 +18,6 @@ For questions, you can also use the `ngless mailing list
         Microbiome 2019 7:84;
         `https://doi.org/10.1186/s40168-019-0684-8 <https://doi.org/10.1186/s40168-019-0684-8>`__
 
-    previously also available as a pre-print at:
-
-        *NG-meta-profiler: fast processing of metagenomes using NGLess, a
-        domain-specific language* by Luis Pedro Coelho, Renato Alves, Paulo
-        Monteiro, Jaime Huerta-Cepas, Ana Teresa Freitas, Peer Bork -
-        bioRxiv 367755;
-        `https://doi.org/10.1101/367755 <https://doi.org/10.1101/367755>`__
-
 
 NG-meta-profiler
 ----------------
@@ -39,7 +31,7 @@ NGLess
 
 NGLess is best illustrated by an example::
 
-    ngless "0.11"
+    ngless "1.0"
     input = paired('ctrl1.fq', 'ctrl2.fq', singles='ctrl-singles.fq')
     input = preprocess(input) using |read|:
         read = read[5:]
@@ -112,7 +104,7 @@ This is equivalent to the full script:
 
 ::
 
-    ngless "0.11" # <- version declaration, optional on the command line
+    ngless "1.0" # <- version declaration, optional on the command line
     samcontents = samfile("file.sam") # <- load a SAM/BAM file
     reads = as_reads(samcontents) # <- just get the reads (w quality scores)
     write(reads, ofname=STDOUT) # <- write them to STDOUT (default format: FASTQ)
@@ -122,7 +114,7 @@ out a single FQ file. Otherwise, you can always do:
 
 ::
 
-    ngless "0.11"
+    ngless "1.0"
     write(as_read(samfile("file.sam")),
             ofile="output.fq")
 
@@ -144,7 +136,7 @@ This is equivalent to the full script:
 
 ::
 
-    ngless "0.11" # <- version declaration, optional on the command line
+    ngless "1.0" # <- version declaration, optional on the command line
     samcontents = samfile("file.sam") # <- load a SAM/BAM file
     samcontents = select(samcontents, keep_if=[{mapped}]) # <- select only *mapped* reads
     reads = as_reads(samcontents) # <- just get the reads (w quality scores)
@@ -188,6 +180,7 @@ Authors
    install
    ng-meta-profiler
    whatsnew
+   backwards
    tutorial-ocean-metagenomics
    tutorial-assembly-gp
    tutorial-gut-metagenomics