`auto_process_ngs.docs`

Provides utility classes and functions to help with generating Sphinx documentation for the auto_process_ngs package.

The helpers are intended to be used within the Sphinx conf.py file, to generate content such as tables of applications and protocols which are then included in the documentation source files, and API and reference documentation.

Classes:

RstSimpleTable: class for making reStructuredText ‘simple’ tables
RstGridTable: class for making reStructuredText ‘grid’ tables
ExampleQCPlots: class for making example QC micro-plots

Functions:

generate_qc_protocols_tbl: generate table of QC protocols
generate_fq_protocols_tbl: generate table of Fastq generation protocols
generate_fq_prototocols_for_apps: table of Fastq generation protocols for specified applications
generate_applications_tbl: generate table of applications
generate_api_docs: generate developer’s API documentation
generate_utility_docs: generate documentation for utilities
generate_command_docs: generate documentation for ‘auto_process’ commands
get_modules: list Python modules in a package
get_help_text: fetch text from running program with ‘–help’

class auto_process_ngs.docs.ExampleQCPlots

Class for generating example QC plots.

Provides a set of static methods for generating example versions of various QC “microplots” (read counts, sequence length distribution, sequence duplication, adapter content, Picard insert sizes, Qualimap gene body coverage and genomic origin),

static adapter_content(images_dir): Generate example adapter content plots

static picard_insert_sizes(images_dir): Generate example Picard insert sizes plots

static qualimap(images_dir): Generate example Qualimp plots

static read_counts(images_dir): Generate example read count plots

static sequence_duplication(images_dir): Generate example sequence duplication plots

static sequence_lengths(images_dir): Generate example sequence length distribution plots

class auto_process_ngs.docs.RstGridTable(table_data)

Class for making reStructuredText ‘grid’ tables.

See documentation for reStructureText grid tables at: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables

Usage:

>>> table_data = [
...     ['col1_row1','col2_row1','col3_row1'],
...     ['col1_row2','col2_row2','col3_row2'],
...     ['col1_row3','col2_row3','col3_row3'],
... ]
>>> header = ['Column 1','Column 2','Column 3']
>>> table = RstGridTable(table_data)
>>> for line in table.construct_table(header=header):
...     print(line)
+-----------+-----------+-----------+
| Column 1  | Column 2  | Column 3  |
+===========+===========+===========+
| col1_row1 | col2_row1 | col3_row1 |
+-----------+-----------+-----------+
| col1_row2 | col2_row2 | col3_row2 |
+-----------+-----------+-----------+
| col1_row3 | col2_row3 | col3_row3 |
+-----------+-----------+-----------+

Where columns with identical values in adjacent rows are merged:

>>> table_data = [
...     ['block1','col2_row1','col3_row1'],
...     ['block1','col2_row2','col3_row2'],
...     ['block2','col2_row3','col3_row3'],
... ]
>>> header = ['Block','Column 2','Column 3']
>>> table = RstGridTable(table_data)
>>> for line in table.construct_table(header=header):
...     print(line)
+--------+-----------+-----------+
| Block  | Column 2  | Column 3  |
+========+===========+===========+
| block1 | col2_row1 | col3_row1 |
|        +-----------+-----------+
|        | col2_row2 | col3_row2 |
+--------+-----------+-----------+
| block2 | col2_row3 | col3_row3 |
+--------+-----------+-----------+

Parameters:: table_data (list) – list of table rows, where each row is a list of column values.

construct_table(header=None, indent='')

Returns reStructuredText table

Parameters:

header (list) – list of column titles to use in the table header (otherwise no header is made)
indent (str) – string to use for indenting each line of the table (default: no indentation)

get_field_widths(header=None): Returns a list of field widths.

make_divider(field_widths, divider_char='-'): Make a row divider

make_header(header, field_widths): Make the table header

class auto_process_ngs.docs.RstSimpleTable(table_data)

Class for making simple reStructuredText tables.

See documentation for reStructureText simple tables at: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-tables

Usage:

>>> table_data = [
...     ['col1_row1','col2_row1','col3_row1'],
...     ['col1_row2','col2_row2','col3_row2'],
...     ['col1_row3','col2_row3','col3_row3'],
... ]
>>> header = ['Column 1','Column 2','Column 3']
>>> table = RstSimpleTable(table_data)
>>> for line in table.construct_table(header=header):
...     print(line)
=========  =========  =========
Column 1   Column 2   Column 3
=========  =========  =========
col1_row1  col2_row1  col3_row1
col1_row2  col2_row2  col3_row2
col1_row3  col2_row3  col3_row3
=========  =========  =========

Parameters:: table_data (list) – list of table rows, where each row is a list of column values.

construct_table(header=None, indent='')

Returns reStructuredText simple table

Parameters:

header (list) – list of column titles to use in the table header (otherwise no header is made)
indent (str) – string to use for indenting each line of the table (default: no indentation)

get_field_widths(header=None): Returns a list of field widths.

make_divider(field_widths): Make a row divider

auto_process_ngs.docs.generate_api_docs(pkg, docdir)

Generate developer’s API documentation

Parameters:

pkg (str) – package to generate API docs for
docdir (str) – path to directory where docs will be written

auto_process_ngs.docs.generate_applications_table(docfile, tags=None)

Generates table of applications

The table will only include applications which match the specified tags (if supplied), and will have the columns ‘Platform’, ‘Library’, and optionally a third column ‘Extensions’ (if at least one application has extensions defined).

Parameters:

docfile (str) – path to output RST file
tags (list) – list of tags to specify which applications should be included in the table

auto_process_ngs.docs.generate_command_docs(cmds, docfile): Generate documentation for ‘auto_process’ commands

auto_process_ngs.docs.generate_fq_protocols_for_apps(docfile, header=['Application', 'Protocol'], tags=None)

Fastq generation protocols table for specific applications

Table lists the Fastq protocols and has columns with application description and protocol name.

Parameters:

docfile (str) – path to output RST file
header (list) – list of column titles to use in the table
tags (list) – list of tags to include in the table

auto_process_ngs.docs.generate_fq_protocols_tbl(docfile)

Generate table with the Fastq generation protocols

Table lists the Fastq protocols and has columns with protocol name, description and read lengths.

Parameters:: docfile (str) – path to output RST file

auto_process_ngs.docs.generate_qc_protocols_tbl(docfile)

Generate table with the QC protocols

Table lists the QC protocols and has columns with protocol name and description.

Parameters:: docfile (str) – path to output RST file

auto_process_ngs.docs.generate_utility_docs(utilities, docfile)

Generate documentation for utility scripts

Parameters:

utilities (list) – list of utility scripts
docfile (str) – path to output document

auto_process_ngs.docs.get_help_text(cmd, *args)

Get help text for a command

Given a command (and optionally any additional arguments), return a string containing the help text.

This is acquired by running the command with the ‘–help’ argument appended.

Parameters:

cmd (str) – command name
args (list) – optional additional arguments

auto_process_ngs.docs.get_modules(pkg, exclude_tests=True)

Get a list of modules in a package

See https://stackoverflow.com/a/1708706/579925

Parameters:

pkg (str) – package name
exclude_tests (bool) – if True (the default) then exclude any modules with names stating with ‘test’

Returns:

list of module names within the package

Return type:

list

auto_process_ngs.docs

`auto_process_ngs.docs`