Documentation

docs/source/Scripts/Binning/binning.rst

@@ -5,6 +5,5 @@ Binning
 .. toctree::
    :maxdepth: 2
    :caption: Table of Contents
-   :glob:
 
    recursive_dbscan

docs/source/Scripts/Common/External/bedtools.rst

@@ -2,20 +2,6 @@
 bedtools.py
 ===========
 
-File containing wrapper functions for bedtools.
-
-**Running the script as stand alone module**
-While in the Autometa directory</path/to/output/file/prots.out> and with the conda environment activated, run: 
-
-.. code-block:: bash
-
-    python -m autometa.common.external.prodigal </path/to/BAM/alignment.bam> 
-    </path/to/genome/output/lengths.tsv> </path/to/output/alignment.bed> --[options]
-
-**Inputs** : ibam file
-
-**Returns** : A tab-delimited table with index = contig and column = coverage
-
 .. rubric:: Usage and command line options
 
 .. program-output:: cd ../.. ; python -m autometa.common.external.bedtools -h

docs/source/Scripts/Common/External/diamond.rst

@@ -2,21 +2,6 @@
 diamond.py
 ==========
 
-File containing class and functions related to running diamond on metagenome sequences
-
-**Running the script as stand alone module**
-While in the Autometa directory and with the conda environment activated, run:
-
-.. code-block:: bash
-
-    python -m autometa.common.external.diamond <path/to/input/file.faa> 
-    </path/to/diamond/formatted/database> </path/to/ncbi/prot.accession2taxid.gz> 
-    </path/to/diamond/output/file> <blastp or blastx> --[options]
-
-**Inputs** : Protein file (faa format)
-
-**Returns** : A dictionary of Blastp hits, with key = qseqid and value = Diamond result
-
 .. rubric:: Usage and command line options
 
 .. program-output:: cd ../.. ; python -m autometa.common.external.diamond -h

docs/source/Scripts/Common/External/prodigal.rst

@@ -2,20 +2,6 @@
 prodigal.py
 ===========
 
-File containing functions to retrieve orfs from provided assembly using prodigal.
-
-**Running the script as stand alone module**
-While in the Autometa directory and with the conda environment activated, run: 
-
-.. code-block:: bash
-
-    python -m autometa.common.external.prodigal </path/to/assembly/input/file> 
-    </path/to/output/file/nucls.out> </path/to/output/file/prots.out> --[options]
-
-**Inputs** : Assembly file (fasta format)
-
-**Returns** : Nucleotide file (ffn format) and protein file (faa format) containing orfs
-
 .. rubric:: Usage and command line options
 
 .. program-output:: cd ../.. ; python -m autometa.common.external.prodigal -h

docs/source/Scripts/Common/common.rst

@@ -2,10 +2,16 @@
 Common
 ======
 
+.. sidebar:: Script under external
+
+    The external directory is a subdirectory of common.
+    All scripts in there come under common.
+
 .. toctree::
 
    External/external
 
+
 .. autosummary::
    :toctree:
 

docs/source/Scripts/Common/kmers.rst

@@ -2,21 +2,6 @@
 kmers.py
 =========
 
-File containing functions to count and retrieve k-mers of a given sequences.
-
-**Running the script as stand alone module**
-While in the Autometa directory and with the conda environment activated, run:
-
-.. code-block:: bash
-
-  python -m autometa.common.kmers --fasta <path/to/input/fasta/file.fasta>
-  --kmers <path/to/output/file.tsv> --[options]
-
-**Inputs** : Assembly file (in fna format), k-mer size
-
-**Returns** : A tab-delimited matrix of k-mer frequency counts with an index column corresponding
-to each contig in the input fasta file
-
 .. rubric:: Usage and command line options
 
 .. program-output:: cd ../.. ; python -m autometa.common.kmers -h

docs/source/Scripts/Common/utilities.rst

@@ -3,7 +3,7 @@ utilities.py
 ============
 
 .. note:: 
-    File containing utilities functions for Autometa pipeline, cannot be run as a standalone module.
+    This file contains custom exceptions for Autometa and should not be run directly
 
 .. rubric:: Functions
 

docs/source/Scripts/Config/config.rst

@@ -7,6 +7,6 @@ Config
    :caption: Table of Contents
 
    databases
-   evnviron
+   environ
    project
    user

docs/source/Scripts/scripts.rst

@@ -5,7 +5,6 @@ Scripts
 .. toctree::
    :maxdepth: 3
    :caption: Table of Contents
-   :glob:
 
    autometa
    Binning/binning

docs/source/_ext/todo.py

@@ -0,0 +1,127 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+from sphinx.locale import _
+from sphinx.util.docutils import SphinxDirective
+
+
+class todo(nodes.Admonition, nodes.Element):
+    pass
+
+
+class todolist(nodes.General, nodes.Element):
+    pass
+
+
+def visit_todo_node(self, node):
+    self.visit_admonition(node)
+
+
+def depart_todo_node(self, node):
+    self.depart_admonition(node)
+
+
+class TodolistDirective(Directive):
+
+    def run(self):
+        return [todolist('')]
+
+
+class TodoDirective(SphinxDirective):
+
+    # this enables content in the directive
+    has_content = True
+
+    def run(self):
+        targetid = 'todo-%d' % self.env.new_serialno('todo')
+        targetnode = nodes.target('', '', ids=[targetid])
+
+        todo_node = todo('\n'.join(self.content))
+        todo_node += nodes.title(_('Todo'), _('Todo'))
+        self.state.nested_parse(self.content, self.content_offset, todo_node)
+
+        if not hasattr(self.env, 'todo_all_todos'):
+            self.env.todo_all_todos = []
+
+        self.env.todo_all_todos.append({
+            'docname': self.env.docname,
+            'lineno': self.lineno,
+            'todo': todo_node.deepcopy(),
+            'target': targetnode,
+        })
+
+        return [targetnode, todo_node]
+
+
+def purge_todos(app, env, docname):
+    if not hasattr(env, 'todo_all_todos'):
+        return
+
+    env.todo_all_todos = [todo for todo in env.todo_all_todos
+                          if todo['docname'] != docname]
+
+
+def process_todo_nodes(app, doctree, fromdocname):
+    if not app.config.todo_include_todos:
+        for node in doctree.traverse(todo):
+            node.parent.remove(node)
+
+    # Replace all todolist nodes with a list of the collected todos.
+    # Augment each todo with a backlink to the original location.
+    env = app.builder.env
+
+    if not hasattr(env, 'todo_all_todos'):
+        env.todo_all_todos = []
+
+    for node in doctree.traverse(todolist):
+        if not app.config.todo_include_todos:
+            node.replace_self([])
+            continue
+
+        content = []
+
+        for todo_info in env.todo_all_todos:
+            para = nodes.paragraph()
+            filename = env.doc2path(todo_info['docname'], base=None)
+            description = (
+                _('(The original entry is located in %s, line %d and can be found ') %
+                (filename, todo_info['lineno']))
+            para += nodes.Text(description, description)
+
+            # Create a reference
+            newnode = nodes.reference('', '')
+            innernode = nodes.emphasis(_('here'), _('here'))
+            newnode['refdocname'] = todo_info['docname']
+            newnode['refuri'] = app.builder.get_relative_uri(
+                fromdocname, todo_info['docname'])
+            newnode['refuri'] += '#' + todo_info['target']['refid']
+            newnode.append(innernode)
+            para += newnode
+            para += nodes.Text('.)', '.)')
+
+            # Insert into the todolist
+            content.append(todo_info['todo'])
+            content.append(para)
+
+        node.replace_self(content)
+
+
+def setup(app):
+    app.add_config_value('todo_include_todos', False, 'html')
+
+    app.add_node(todolist)
+    app.add_node(todo,
+                 html=(visit_todo_node, depart_todo_node),
+                 latex=(visit_todo_node, depart_todo_node),
+                 text=(visit_todo_node, depart_todo_node))
+
+    app.add_directive('todo', TodoDirective)
+    app.add_directive('todolist', TodolistDirective)
+    app.connect('doctree-resolved', process_todo_nodes)
+    app.connect('env-purge-doc', purge_todos)
+
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/source/conf.py

@@ -11,14 +11,10 @@
 from datetime import datetime
 
 
-sys.path.insert(0, os.path.abspath('../..'))
-sys.path.insert(0, os.path.abspath('../../autometa/common'))
-sys.path.insert(0, os.path.abspath('../../autometa/config'))
-sys.path.insert(0, os.path.abspath('../../autometa/binning'))
-sys.path.insert(0, os.path.abspath('../../autometa/datasets'))
-sys.path.insert(0, os.path.abspath('../../autometa/validation'))
-sys.path.insert(0, os.path.abspath('../../autometa/taxonomy'))
-sys.path.insert(0, os.path.abspath('../../autometa/common/external'))
+sys.path.append(os.path.abspath("./_ext"))
+
+for (dir_path,dir_names,file_name) in os.walk('../../', topdown=True): 
+    sys.path.insert(0, os.path.abspath(dir_path))
 
 # -- Project information -----------------------------------------------------
 
@@ -38,6 +34,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.coverage',

docs/source/contribution-guidelines.rst

@@ -2,6 +2,5 @@
 Contribution Guidelines
 =======================
 
-Guidelines about how to contribute
+.. todo:: Guidelines about how to contribute
 
-Can link this to the GitHub page ?

docs/source/examining-results.rst

@@ -3,7 +3,7 @@ Examining Results
 =================
 
 
-TODO: Overview of figures/summaries generated from results.
+.. todo:: Overview of figures/summaries generated from results.
 
 
 .. csv-table:: Autometa Results

docs/source/index.rst

@@ -2,19 +2,11 @@
 Autometa documentation
 ======================
 
-**Autometa: automated extraction of microbial genomes from individual shotgun metagenomes**
+| **Autometa: automated extraction of microbial genomes from individual shotgun metagenomes**
+| An automated binning pipeline for single metagenomes, in particular host-associated and highly complex ones. 
 
-An automated binning pipeline for single metagenomes, in particular
-host-associated and highly complex ones. Autometa is copyright 2020
-Ian J. Miller, Evan R. Rees, Izaak Miller and Jason C. Kwan, and is
-released under the GNU Affero General Public License v3 (see :ref:`License`).
-
-If you find Autometa useful to your work, please cite our Autometa_ paper:
-
-Miller, I. J.; Rees, E. R.; Ross, J.; Miller, I.; Baxa, J.; Lopera, J.; 
-Kerby, R. L.; Rey, F. E.; Kwan, J. C. Autometa: Automated extraction of microbial 
-genomes from individual shotgun metagenomes. *Nucleic Acids Research*, **2019**. 
-DOI: https://doi.org/10.1093/nar/gkz148
+| If you find Autometa useful to your work, please cite our Autometa_ paper:
+| Miller, I. J.; Rees, E. R.; Ross, J.; Miller, I.; Baxa, J.; Lopera, J.; Kerby, R. L.; Rey, F. E.; Kwan, J. C. Autometa: Automated extraction of microbial  genomes from individual shotgun metagenomes. *Nucleic Acids Research*, **2019**.  DOI: https://doi.org/10.1093/nar/gkz148
 
 Quickstart
 ==========
@@ -38,11 +30,16 @@ Guide
    api
    license
 
+
 Contact
 -------
 For suggestions, queries or appreciation feel free to contact `Dr.JasonKwan <https://apps.pharmacy.wisc.edu/sopdir/jason_kwan/>`_
 at jason.kwan@wisc.edu
 
+Copyright and License
+---------------------
+Autometa is copyright 2020 Ian J. Miller, Evan R. Rees, Izaak Miller and Jason C. Kwan, 
+and is released under the GNU Affero General Public License v3 (see :ref:`License`).
 
 Indices and tables
 ------------------

docs/source/install.rst

@@ -40,4 +40,3 @@ Now download autometa to your desired directory using:
 
     ``git clone https://github.com/KwanLab/Autometa.git``
 
-You should now add the Autometa directory to your $PATH environmental variable