Skip to content

Commit

Permalink
doc: Suppress comment lines at beginning of modules, relates to #86
Browse files Browse the repository at this point in the history
  • Loading branch information
@tomazc
tomazc committed Nov 22, 2016
1 parent 1fa7792 commit 0ab17ed
Show file tree
Hide file tree
Showing 3 changed files with 39 additions and 86 deletions.
95 changes: 14 additions & 81 deletions docs/source/ref_CLI.txt
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
usage: iCount [-h] [-v] ...

.. Line to protect from pydocstyle D205, D400.

iCount: protein-RNA interaction analysis
========================================

Expand All @@ -25,19 +23,19 @@ Commands:
species Get list of species for given release.
annotation Download annotation in GTF file fromat.
genome Download genome file in FASTA fromat.
segment .. Line to protect from pydocstyle D205, D400.
demultiplex .. Line to protect from pydocstyle D205, D400.
cutadapt .. Line to protect from pydocstyle D205, D400.
indexstar .. Line to protect from pydocstyle D205, D400.
mapstar .. Line to protect from pydocstyle D205, D400.
xlsites .. Line to protect from pydocstyle D205, D400.
annotate .. Line to protect from pydocstyle D205, D400.
clusters .. Line to protect from pydocstyle D205, D400.
group .. Line to protect from pydocstyle D205, D400.
peaks .. Line to protect from pydocstyle D205, D400.
rnamaps .. Line to protect from pydocstyle D205, D400.
summary .. Line to protect from pydocstyle D205, D400.
examples .. Line to protect from pydocstyle D205, D400.
segment Parse genome annotation, segment it and prepare a number of versions needed
demultiplex Split FASTQ file into separate FASTQ files, one for each sample barcode.
cutadapt Interface to running cutadapt.
indexstar Call STAR to generate genome index, which is used for mapping.
mapstar Call STAR to map reads to genome index and produce BAM file.
xlsites Determine positions and quantity of cross-link events.
annotate Annotate each cross link site with types of regions that intersect with it.
clusters Merge adjacent cross-linked sites into clusters.
group Merge BED files into one BED file.
peaks Find positions with high density of cross-linked sites.
rnamaps Distribution of cross-links relative to genomic landmarks.
summary Report proportion of cross-link events/sites on each region type
examples This module provides a set of example bash scripts that can be run by the user.
man Print help for all commands.
args Print arguments form all CLI commands

Expand Down Expand Up @@ -141,11 +139,6 @@ segment
usage: iCount segment [-h] [-prog] [-S] [-F] [-P] [-M]
annotation segmentation fai

.. Line to protect from pydocstyle D205, D400.

Segmentation
------------

Parse genome annotation, segment it and prepare a number of versions needed
for mapping and for various analyses:

Expand Down Expand Up @@ -174,11 +167,6 @@ usage: iCount demultiplex [-h] [-mis] [-ml] [--prefix] [-od] [-S] [-F] [-P]
[-M]
reads adapter barcodes [barcodes ...]

.. Line to protect from pydocstyle D205, D400.

Demultiplexing
==============

Split FASTQ file into separate FASTQ files, one for each sample barcode.
Saved FASTQ files contain sequences where sample barcode, random
barcode, and adapter sequences were removed. Random barcode is moved into
Expand Down Expand Up @@ -213,11 +201,6 @@ usage: iCount cutadapt [-h] [--qual_base] [--qual_trim] [-ml] [-S] [-F] [-P]
[-M]
reads reads_trimmed adapter

.. Line to protect from pydocstyle D205, D400.

Cutadapt
--------

Interface to running cutadapt.

positional arguments:
Expand Down Expand Up @@ -245,11 +228,6 @@ usage: iCount indexstar [-h] [-a] [--overhang] [--overhang_min] [--threads]
[-S] [-F] [-P] [-M]
genome genome_index

.. Line to protect from pydocstyle D205, D400.

Generate STAR index
-------------------

Call STAR to generate genome index, which is used for mapping.

Calls STAR to generate index based on genome sequence and annotation,
Expand Down Expand Up @@ -286,11 +264,6 @@ usage: iCount mapstar [-h] [-a] [--multimax] [-mis] [--threads] [-S] [-F] [-P]
[-M]
reads genome_index out_dir

.. Line to protect from pydocstyle D205, D400.

Map using STAR
--------------

Call STAR to map reads to genome index and produce BAM file.

Calls STAR to map sequence reads to reference genome, by passing the
Expand Down Expand Up @@ -331,11 +304,6 @@ usage: iCount xlsites [-h] [-g] [--quant] [--segmentation] [-mis] [--mapq_th]
[--multimax] [--gap_th] [-prog] [-S] [-F] [-P] [-M]
bam sites_unique sites_multi skipped

.. Line to protect from pydocstyle D205, D400.

Identify and quantify cross-linked sites
----------------------------------------

Determine positions and quantity of cross-link events.

The simplest version of this script would oprate on such example::
Expand Down Expand Up @@ -444,11 +412,6 @@ annotate
usage: iCount annotate [-h] [--subtype] [-e [...]] [-S] [-F] [-P] [-M]
annotation sites sites_annotated

.. Line to protect from pydocstyle D205, D400.

Cross-link site annotation
--------------------------

Annotate each cross link site with types of regions that intersect with it.

positional arguments:
Expand All @@ -472,11 +435,6 @@ clusters

usage: iCount clusters [-h] [--dist] [-S] [-F] [-P] [-M] sites clusters

.. Line to protect from pydocstyle D205, D400.

Cluster sites
-------------

Merge adjacent cross-linked sites into clusters.

Read bedGraph with (significant) cross-linked sites. Cluster together sites that
Expand All @@ -501,12 +459,7 @@ group

usage: iCount group [-h] [-S] [-F] [-P] [-M] sites_grouped sites [sites ...]

.. Line to protect from pydocstyle D205, D400.

Group BED files
---------------

Group analysis docstring... TODO!
Merge BED files into one BED file.

positional arguments:
sites_grouped Path to output BED6 file containing merged data from input sites files
Expand All @@ -528,11 +481,6 @@ usage: iCount peaks [-h] [--scores] [--features [...]] [-g]
[-prog] [-S] [-F] [-P] [-M]
annotation sites peaks

.. Line to protect from pydocstyle D205, D400.

Peak finding
------------

Find positions with high density of cross-linked sites.

There are two typical variants of this analysis, depending on the parameters:
Expand Down Expand Up @@ -678,11 +626,6 @@ usage: iCount rnamaps [-h] [--implicit_handling] [-mis] [--mapq_th]
[--holesize_th] [-S] [-F] [-P] [-M]
bam segmentation out_file strange cross_transcript

.. Line to protect from pydocstyle D205, D400.

RNA maps
--------

Distribution of cross-links relative to genomic landmarks.

What is an RNA-map?
Expand Down Expand Up @@ -852,11 +795,6 @@ usage: iCount summary [-h] [--types_length_file] [--digits] [--subtype]
[-e [...]] [-S] [-F] [-P] [-M]
annotation sites summary fai

.. Line to protect from pydocstyle D205, D400.

Cross-link site summary
-----------------------

Report proportion of cross-link events/sites on each region type

positional arguments:
Expand All @@ -883,11 +821,6 @@ examples

usage: iCount examples [-h] [-od] [-S] [-F] [-P] [-M]

.. Line to protect from pydocstyle D205, D400.

Examples
========

This module provides a set of example bash scripts that can be run by the user.
The included script ``tutorial.sh`` replicates all the steps described in the tutorial.

Expand Down
3 changes: 2 additions & 1 deletion iCount/analysis/group.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
Group BED files
---------------
Group analysis docstring... TODO!
Merge BED files into one BED file.
"""
# pylint: disable=unused-import
from .. files.bed import merge_bed as run
27 changes: 23 additions & 4 deletions iCount/cli.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,20 @@ def _list_str(string, separator=','):
PARAMETERS = {}


def remove_comments(description):
"""
Remove reStructuredText comment lines.
"""
description = description.splitlines()
if len(description) > 0:
if description[0].startswith('..'):
description = description[1:]
while description and description[0].strip() == '':
description.pop(0)

return '\n'.join(description)

def _format_defaults(value):
"""
Format value to CLI syntax.
Expand Down Expand Up @@ -186,7 +200,7 @@ def make_parser_from_function(function, subparsers, module=None, only_func=False
* Positional and optional arguments (and default values) are sourced
from function signature
* Help text for each of the arguments is sourced from function
docstring. For this to work functions needs to follow Nummpy docstrig
docstring. For this to work functions needs to follow Nummpy docstring
formatting. All parameters should have meaningful description. All
parameters should also have type equal to one of the keys in
VALID_TYPES.
Expand Down Expand Up @@ -218,7 +232,7 @@ def make_parser_from_function(function, subparsers, module=None, only_func=False
* In some cases function that performs the work is only *imported* in the
correct module ("exposed module"), but the actual function definition is
loctated somewhere else ("source module"). It that case, one can use
located somewhere else ("source module"). It that case, one can use
``module`` parameter with "source module" value. In this case, the
command name and CLI docstring will be defined from "exposed module" but
function, default values and parameter descriptions will be sourced from
Expand All @@ -227,26 +241,31 @@ def make_parser_from_function(function, subparsers, module=None, only_func=False
* In some cases, there will be more CLI exposed functions in the same
module. In such case, use set ``only_func`` parameter to ``True``. This will
use function name for CLI command name and use function docstring (form
beggining until "Parameters" section) for CLI help message.
beginning until "Parameters" section) for CLI help message.
"""
if module:
# Command name is determined from module name:
name = module.__name__.split('.')[-1]
# Description is determined from module docstring:
description = inspect.getdoc(module)
description = remove_comments(description)
description = '\n'.join(description.split('\n')[3:])
elif only_func:
# If only_func=True than name of the command equals function name
name = function.__name__
# Take only the docstring until the 'Parameters' section:
desc = inspect.getdoc(function).split('\n')
idx = [i for i, d in enumerate(desc) if d == 'Parameters' or d == 'Returns'][0]
description = '\n'.join(desc[:idx])
description = remove_comments(description)
else:
# Command name is determined from module name:
name = inspect.getmodule(function).__name__.split('.')[-1]
# Description is determined from module docstring:
description = inspect.getdoc(inspect.getmodule(function))
description = remove_comments(description)
description = '\n'.join(description.split('\n')[3:])

if not description:
description = 'No description provided.'
Expand Down Expand Up @@ -302,7 +321,7 @@ def main():
#####################

root_parser = argparse.ArgumentParser(
description=inspect.getdoc(iCount).split('\n..')[0],
description=remove_comments(inspect.getdoc(iCount)).split('\n..')[0],
formatter_class=argparse.RawTextHelpFormatter # ArgumentDefaultsHelpFormatter,
)
# Parser (general) arguments
Expand Down

0 comments on commit 0ab17ed

Please sign in to comment.