Normalise channel docs

Signed-off-by: Paolo Di Tommaso <[email protected]>

Author: pditommaso

docs/channel.md

@@ -70,7 +70,7 @@ Channels may be created explicitly using the following channel factory methods.
 
 ### empty
 
-The `empty` factory method, by definition, creates a channel that doesn't emit any value.
+The `channel.empty` factory method, by definition, creates a channel that doesn't emit any value.
 
 See also: {ref}`operator-ifempty`.
 
@@ -79,13 +79,13 @@ See also: {ref}`operator-ifempty`.
 ### from
 
 :::{deprecated} 19.09.0-edge
-Use [of](#of) or [fromList](#fromlist) instead.
+Use [channel.of](#of) or [channel.fromList](#fromlist) instead.
 :::
 
-The `from` method allows you to create a channel emitting any sequence of values that are specified as the method argument, for example:
+The `channel.from` method allows you to create a channel emitting any sequence of values that are specified as the method argument, for example:
 
 ```groovy
-ch = Channel.from( 1, 3, 5, 7 )
+ch = channel.from( 1, 3, 5, 7 )
 ch.subscribe { println "value: $it" }
 ```
 
@@ -101,25 +101,25 @@ value: 7
 The following example shows how to create a channel from a *range* of numbers or strings:
 
 ```groovy
-zeroToNine = Channel.from( 0..9 )
-strings = Channel.from( 'A'..'Z' )
+zeroToNine = channel.from( 0..9 )
+strings = channel.from( 'A'..'Z' )
 ```
 
 :::{note}
-When the `from` argument is an object implementing the (Java) [Collection](http://docs.oracle.com/javase/7/docs/api/java/util/Collection.html) interface, the resulting channel emits the collection entries as individual items.
+When the `channel.from` argument is an object implementing the (Java) [Collection](http://docs.oracle.com/javase/7/docs/api/java/util/Collection.html) interface, the resulting channel emits the collection entries as individual items.
 :::
 
 Thus the following two declarations produce an identical result even though in the first case the items are specified as multiple arguments while in the second case as a single list object argument:
 
 ```groovy
-Channel.from( 1, 3, 5, 7, 9 )
-Channel.from( [1, 3, 5, 7, 9] )
+channel.from( 1, 3, 5, 7, 9 )
+channel.from( [1, 3, 5, 7, 9] )
 ```
 
 But when more than one argument is provided, they are always managed as *single* emissions. Thus, the following example creates a channel emitting three entries each of which is a list containing two elements:
 
 ```groovy
-Channel.from( [1, 2], [5,6], [7,9] )
+channel.from( [1, 2], [5,6], [7,9] )
 ```
 
 (channel-fromlist)=
@@ -129,10 +129,10 @@ Channel.from( [1, 2], [5,6], [7,9] )
 :::{versionadded} 19.10.0
 :::
 
-The `fromList` method allows you to create a channel emitting the values provided as a list of elements, for example:
+The `channel.fromList` method allows you to create a channel emitting the values provided as a list of elements, for example:
 
 ```groovy
-Channel
+channel
     .fromList( ['a', 'b', 'c', 'd'] )
     .view { "value: $it" }
 ```
@@ -146,28 +146,31 @@ value: c
 value: d
 ```
 
-See also: [of](#of) factory method.
+See also: [channel.of](#of) factory method.
 
 (channel-path)=
 
 ### fromPath
 
-You can create a channel emitting one or more file paths by using the `fromPath` method and specifying a path string as an argument. For example:
+You can create a channel emitting one or more file paths by using the `channel.fromPath` method and specifying a path
+string as an argument. For example:
 
 ```groovy
-myFileChannel = Channel.fromPath( '/data/some/bigfile.txt' )
+myFileChannel = channel.fromPath( '/data/some/bigfile.txt' )
 ```
 
-The above line creates a channel and binds it to a [Path](http://docs.oracle.com/javase/7/docs/api/java/nio/file/Path.html) object for the specified file.
+The above line creates a channel and binds it to a [Path](http://docs.oracle.com/javase/7/docs/api/java/nio/file/Path.html)
+object for the specified file.
 
 :::{note}
-`fromPath` does not check whether the file exists.
+`channel.fromPath` does not check whether the file exists.
 :::
 
-Whenever the `fromPath` argument contains a `*` or `?` wildcard character it is interpreted as a [glob][glob] path matcher. For example:
+Whenever the `channel.fromPath` argument contains a `*` or `?` wildcard character it is interpreted as a [glob][glob] path matcher.
+For example:
 
 ```groovy
-myFileChannel = Channel.fromPath( '/data/big/*.txt' )
+myFileChannel = channel.fromPath( '/data/big/*.txt' )
 ```
 
 This example creates a channel and emits as many `Path` items as there are files with `txt` extension in the `/data/big` folder.
@@ -179,9 +182,9 @@ Two asterisks, i.e. `**`, works like `*` but crosses directory boundaries. This
 For example:
 
 ```groovy
-files = Channel.fromPath( 'data/**.fa' )
-moreFiles = Channel.fromPath( 'data/**/*.fa' )
-pairFiles = Channel.fromPath( 'data/file_{1,2}.fq' )
+files = channel.fromPath( 'data/**.fa' )
+moreFiles = channel.fromPath( 'data/**/*.fa' )
+pairFiles = channel.fromPath( 'data/file_{1,2}.fq' )
 ```
 
 The first line returns a channel emitting the files ending with the suffix `.fa` in the `data` folder *and* recursively in all its sub-folders. While the second one only emits the files which have the same suffix in *any* sub-folder in the `data` path. Finally the last example emits two files: `data/file_1.fq` and `data/file_2.fq`.
@@ -193,15 +196,15 @@ As in Linux Bash, the `*` wildcard does not catch hidden files (i.e. files whose
 Multiple paths or glob patterns can be specified using a list:
 
 ```groovy
-Channel.fromPath( ['/some/path/*.fq', '/other/path/*.fastq'] )
+channel.fromPath( ['/some/path/*.fq', '/other/path/*.fastq'] )
 ```
 
 In order to include hidden files, you need to start your pattern with a period character or specify the `hidden: true` option. For example:
 
 ```groovy
-expl1 = Channel.fromPath( '/path/.*' )
-expl2 = Channel.fromPath( '/path/.*.fa' )
-expl3 = Channel.fromPath( '/path/*', hidden: true )
+expl1 = channel.fromPath( '/path/.*' )
+expl2 = channel.fromPath( '/path/.*.fa' )
+expl3 = channel.fromPath( '/path/*', hidden: true )
 ```
 
 The first example returns all hidden files in the specified path. The second one returns all hidden files ending with the `.fa` suffix. Finally the last example returns all files (hidden and non-hidden) in that path.
@@ -211,8 +214,8 @@ By default a [glob][glob] pattern only looks for regular file paths that match t
 You can use the `type` option specifying the value `file`, `dir` or `any` in order to define what kind of paths you want. For example:
 
 ```groovy
-myFileChannel = Channel.fromPath( '/path/*b', type: 'dir' )
-myFileChannel = Channel.fromPath( '/path/a*', type: 'any' )
+myFileChannel = channel.fromPath( '/path/*b', type: 'dir' )
+myFileChannel = channel.fromPath( '/path/a*', type: 'any' )
 ```
 
 The first example will return all *directory* paths ending with the `b` suffix, while the second will return any file or directory starting with a `a` prefix.
@@ -244,10 +247,11 @@ Available options:
 
 ### fromFilePairs
 
-The `fromFilePairs` method creates a channel emitting the file pairs matching a [glob][glob] pattern provided by the user. The matching files are emitted as tuples in which the first element is the grouping key of the matching pair and the second element is the list of files (sorted in lexicographical order). For example:
+The `channel.fromFilePairs` method creates a channel emitting the file pairs matching a [glob][glob] pattern provided
+by the user. The matching files are emitted as tuples in which the first element is the grouping key of the matching pair and the second element is the list of files (sorted in lexicographical order). For example:
 
 ```groovy
-Channel
+channel
     .fromFilePairs('/my/data/SRR*_{1,2}.fastq')
     .view()
 ```
@@ -270,13 +274,13 @@ The glob pattern must contain at least one `*` wildcard character.
 Multiple glob patterns can be specified using a list:
 
 ```groovy
-Channel.fromFilePairs( ['/some/data/SRR*_{1,2}.fastq', '/other/data/QFF*_{1,2}.fastq'] )
+channel.fromFilePairs( ['/some/data/SRR*_{1,2}.fastq', '/other/data/QFF*_{1,2}.fastq'] )
 ```
 
 Alternatively, it is possible to implement a custom file pair grouping strategy providing a closure which, given the current file as parameter, returns the grouping key. For example:
 
 ```groovy
-Channel
+channel
     .fromFilePairs('/some/data/*', size: -1) { file -> file.extension }
     .view { ext, files -> "Files with the extension $ext are $files" }
 ```
@@ -311,10 +315,10 @@ Available options:
 :::{versionadded} 19.04.0
 :::
 
-The `fromSRA` method queries the [NCBI SRA](https://www.ncbi.nlm.nih.gov/sra) database and returns a channel emitting the FASTQ files matching the specified criteria i.e project or accession number(s). For example:
+The `channel.fromSRA` method queries the [NCBI SRA](https://www.ncbi.nlm.nih.gov/sra) database and returns a channel emitting the FASTQ files matching the specified criteria i.e project or accession number(s). For example:
 
 ```groovy
-Channel
+channel
     .fromSRA('SRP043510')
     .view()
 ```
@@ -335,7 +339,7 @@ Multiple accession IDs can be specified using a list object:
 
 ```groovy
 ids = ['ERR908507', 'ERR908506', 'ERR908505']
-Channel
+channel
     .fromSRA(ids)
     .view()
 ```
@@ -356,7 +360,7 @@ To access the ESearch API, you must provide your [NCBI API keys](https://ncbiins
 
 - The `apiKey` option:
   ```groovy
-  Channel.fromSRA(ids, apiKey:'0123456789abcdef')
+  channel.fromSRA(ids, apiKey:'0123456789abcdef')
   ```
 
 - The `NCBI_API_KEY` variable in your environment:
@@ -385,14 +389,15 @@ Available options:
 :::{versionadded} 19.10.0
 :::
 
-The `of` method allows you to create a channel that emits the arguments provided to it, for example:
+The `channel.of` method allows you to create a channel that emits the arguments provided to it, for example:
 
 ```groovy
-ch = Channel.of( 1, 3, 5, 7 )
+ch = channel.of( 1, 3, 5, 7 )
 ch.view { "value: $it" }
 ```
 
-The first line in this example creates a variable `ch` which holds a channel object. This channel emits the arguments supplied to the `of` method. Thus the second line prints the following:
+The first line in this example creates a variable `ch` which holds a channel object. This channel emits the arguments
+supplied to the `of` method. Thus the second line prints the following:
 
 ```
 value: 1
@@ -404,7 +409,7 @@ value: 7
 Ranges of values are expanded accordingly:
 
 ```groovy
-Channel
+channel
     .of(1..23, 'X', 'Y')
     .view()
 ```
@@ -422,37 +427,42 @@ X
 Y
 ```
 
-See also: [fromList](#fromlist) factory method.
+See also: [channel.fromList](#fromlist) factory method.
 
 (channel-value)=
 
 ### value
 
-The `value` method is used to create a value channel. An optional (not `null`) argument can be specified to bind the channel to a specific value. For example:
+The `channel.value` method is used to create a value channel. An optional (not `null`) argument can be specified to bind
+the channel to a specific value. For example:
 
 ```groovy
-expl1 = Channel.value()
-expl2 = Channel.value( 'Hello there' )
-expl3 = Channel.value( [1,2,3,4,5] )
+expl1 = channel.value()
+expl2 = channel.value( 'Hello there' )
+expl3 = channel.value( [1,2,3,4,5] )
 ```
 
-The first line in the example creates an 'empty' variable. The second line creates a channel and binds a string to it. The third line creates a channel and binds a list object to it that will be emitted as a single value.
+The first line in the example creates an 'empty' variable. The second line creates a channel and binds a string to it.
+The third line creates a channel and binds a list object to it that will be emitted as a single value.
 
 (channel-watchpath)=
 
 ### watchPath
 
-The `watchPath` method watches a folder for one or more files matching a specified pattern. As soon as there is a file that meets the specified condition, it is emitted over the channel that is returned by the `watchPath` method. The condition on files to watch can be specified by using `*` or `?` wildcard characters i.e. by specifying a [glob][glob] path matching criteria.
+The `channel.watchPath` method watches a folder for one or more files matching a specified pattern. As soon as there
+is a file that meets the specified condition, it is emitted over the channel that is returned by the `watchPath` method.
+The condition on files to watch can be specified by using `*` or `?` wildcard characters i.e. by specifying a [glob][glob] path matching criteria.
 
 For example:
 
 ```groovy
-Channel
+channel
     .watchPath( '/path/*.fa' )
     .subscribe { println "Fasta file: $it" }
 ```
 
-By default it watches only for new files created in the specified folder. Optionally, it is possible to provide a second argument that specifies what event(s) to watch. The supported events are:
+By default it watches only for new files created in the specified folder. Optionally, it is possible to provide a second
+argument that specifies what event(s) to watch. The supported events are:
 
 - `create`: A new file is created (default)
 - `modify`: A file is modified
@@ -461,15 +471,17 @@ By default it watches only for new files created in the specified folder. Option
 You can specify more than one of these events by using a comma separated string as shown below:
 
 ```groovy
-Channel
+channel
     .watchPath( '/path/*.fa', 'create,modify' )
     .subscribe { println "File created or modified: $it" }
 ```
 
 :::{warning}
-The `watchPath` factory waits endlessly for files that match the specified pattern and event(s), which means that it will cause your pipeline to run forever. Consider using the `take` or `until` operator to close the channel when a certain condition is met (e.g. after receiving 10 files, receiving a file named `DONE`).
+The `channel.watchPath` factory waits endlessly for files that match the specified pattern and event(s), which means
+that it will cause your pipeline to run forever. Consider using the `take` or `until` operator to close the channel when
+a certain condition is met (e.g. after receiving 10 files, receiving a file named `DONE`).
 :::
 
-See also: [fromPath](#frompath) factory method.
+See also: [channel.fromPath](#frompath) factory method.
 
 [glob]: http://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob