Merge pull request #47 from tripal/docs

Add RTD Docs

.gitignore

@@ -6,4 +6,5 @@ js/*
 ## Ignore PHPUnit Test vendor scripts & environment info.
 .env
 vendor/
+docs/_build
 

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/theme_overrides.css

@@ -0,0 +1,181 @@
+/* override table width restrictions
+See: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html
+ */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}
+
+/**
+ * Buttons on Extension Module pages.
+ */
+#administrative .section p:last-child a,
+  #analysis-annotation .section p:last-child a,
+  #data-loading-collection .section p:last-child a,
+  #developer-tools .section p:last-child a,
+  #third-party-integration .section p:last-child a,
+  #searching .section p:last-child a,
+  #visualization-display .section p:last-child a {
+   font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
+   display: inline-block;
+   vertical-align: middle;
+   text-align: center;
+   border-radius: 4px;
+   margin-bottom: 20px;
+   margin-right: 8px;
+   -webkit-font-smoothing: antialiased;
+   letter-spacing: 0.03em;
+   font-weight: 500;
+   line-height: 14px;
+   font-size: 14px;
+   padding: 9px 10px;
+   color: #666666;
+   background: #FFFFFF;
+   background: -webkit-linear-gradient(top, #FFFFFF, #f1f1f1);
+   border: 1px solid #c8c8c8;
+   box-shadow: 0 1px 0px #e9e9e9;
+ }
+ #administrative .section p:last-child a:hover,
+   #analysis-annotation .section p:last-child a:hover,
+   #data-loading-collection .section p:last-child a:hover,
+   #developer-tools .section p:last-child a:hover,
+   #third-party-integration .section p:last-child a:hover,
+   #searching .section p:last-child a:hover,
+   #visualization-display .section p:last-child a:hover  {
+  background: -webkit-linear-gradient(top, #FFFFFF, #e6e6e6);
+}
+
+/**
+ * BRANDING
+ */
+
+/* Sidebar Title */
+.wy-side-nav-search {
+  background: none !important;
+}
+.wy-side-nav-search input[type="text"] {
+  border-color: black;
+}
+.wy-nav-side {
+  color: #CCCCCC !important;
+  background: #2D2D34 !important;
+  background-image: url("hexagon_pattern.png") !important;
+  background-repeat: repeat !important;
+  background: -webkit-linear-gradient(left, $light-grey , $gray-base) !important;
+  background: linear-gradient(to right, $light-grey , $gray-base) !important;
+}
+/* Logo */
+.fa-home::before, .icon-home::before {
+  content: url('small_logoonly.png')
+}
+/* Sidebar TOC */
+.wy-menu-vertical li.current {
+  color: #CCCCCC;
+  border-color: black;
+  background: rgba(0,0,0,0.5);
+}
+.wy-menu-vertical li.toctree-l1.current > a {
+  color: black;
+  border-color: whitesmoke;
+  background-color: whitesmoke;
+}
+.wy-menu-vertical li.toctree-l2.current > a,
+  .wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a,
+  .wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a {
+    color: #CCCCCC;
+    border-color: black;
+    background-color: rgba(0,0,0,0.05);
+}
+.wy-menu-vertical li.current a:hover,
+  .wy-menu-vertical li.toctree-l1.current > a:hover,
+  .wy-menu-vertical li.toctree-l2.current > a:hover,
+  .wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:hover,
+  .wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a:hover {
+    color: white;
+    border-color: black;
+    font-weight: bold;
+    background-color: rgba(0,0,0);
+}
+.wy-menu-vertical li.toctree-l1 a,
+  .wy-menu-vertical li.toctree-l2 a,
+  .wy-menu-vertical li.toctree-l3 a,
+  .wy-menu-vertical li.toctree-l4 a {
+    color: #CCCCCC;
+    border-color: black;
+}
+/* Main Content */
+.wy-nav-content-wrap {
+  background: whitesmoke;
+}
+a, a:hover {
+  color: #990000;
+}
+a:visited {
+  color: #cc0000;
+}
+a.icon-home:visited {
+  color: #ffffff;
+}
+/* Code blocks */
+.highlight {
+  background: #e1f0db;
+}
+/* Default Notes */
+.wy-alert.wy-alert-info,
+  .rst-content .note,
+  .rst-content .wy-alert-info.attention,
+  .rst-content .wy-alert-info.caution,
+  .rst-content .wy-alert-info.danger,
+  .rst-content .wy-alert-info.error,
+  .rst-content .wy-alert-info.hint,
+  .rst-content .wy-alert-info.important,
+  .rst-content .wy-alert-info.tip,
+  .rst-content .wy-alert-info.warning,
+  .rst-content .seealso, .rst-content
+  .wy-alert-info.admonition-todo,
+  .rst-content .wy-alert-info.admonition {
+    background: #d9d9d9;
+}
+.wy-alert.wy-alert-info
+  .wy-alert-title,
+  .rst-content .note .wy-alert-title,
+  .rst-content .wy-alert-info.attention .wy-alert-title,
+  .rst-content .wy-alert-info.caution .wy-alert-title,
+  .rst-content .wy-alert-info.danger .wy-alert-title,
+  .rst-content .wy-alert-info.error .wy-alert-title,
+  .rst-content .wy-alert-info.hint .wy-alert-title,
+  .rst-content .wy-alert-info.important .wy-alert-title,
+  .rst-content .wy-alert-info.tip .wy-alert-title,
+  .rst-content .wy-alert-info.warning .wy-alert-title,
+  .rst-content .seealso .wy-alert-title,
+  .rst-content .wy-alert-info.admonition-todo .wy-alert-title,
+  .rst-content .wy-alert-info.admonition .wy-alert-title,
+  .wy-alert.wy-alert-info .rst-content .admonition-title,
+  .rst-content .wy-alert.wy-alert-info .admonition-title,
+  .rst-content .note .admonition-title,
+  .rst-content .wy-alert-info.attention .admonition-title,
+  .rst-content .wy-alert-info.caution .admonition-title,
+  .rst-content .wy-alert-info.danger .admonition-title,
+  .rst-content .wy-alert-info.error .admonition-title,
+  .rst-content .wy-alert-info.hint .admonition-title,
+  .rst-content .wy-alert-info.important .admonition-title,
+  .rst-content .wy-alert-info.tip .admonition-title,
+  .rst-content .wy-alert-info.warning .admonition-title,
+  .rst-content .seealso .admonition-title, .rst-content
+  .wy-alert-info.admonition-todo .admonition-title,
+  .rst-content .wy-alert-info.admonition .admonition-title {
+    background: #737373;
+}
+/* Note Warnings */
+.wy-alert.wy-alert-warning .wy-alert-title, .rst-content .wy-alert-warning.note .wy-alert-title, .rst-content .attention .wy-alert-title, .rst-content .caution .wy-alert-title, .rst-content .wy-alert-warning.danger .wy-alert-title, .rst-content .wy-alert-warning.error .wy-alert-title, .rst-content .wy-alert-warning.hint .wy-alert-title, .rst-content .wy-alert-warning.important .wy-alert-title, .rst-content .wy-alert-warning.tip .wy-alert-title, .rst-content .warning .wy-alert-title, .rst-content .wy-alert-warning.seealso .wy-alert-title, .rst-content .admonition-todo .wy-alert-title, .rst-content .wy-alert-warning.admonition .wy-alert-title, .wy-alert.wy-alert-warning .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-warning .admonition-title, .rst-content .wy-alert-warning.note .admonition-title, .rst-content .attention .admonition-title, .rst-content .caution .admonition-title, .rst-content .wy-alert-warning.danger .admonition-title, .rst-content .wy-alert-warning.error .admonition-title, .rst-content .wy-alert-warning.hint .admonition-title, .rst-content .wy-alert-warning.important .admonition-title, .rst-content .wy-alert-warning.tip .admonition-title, .rst-content .warning .admonition-title, .rst-content .wy-alert-warning.seealso .admonition-title, .rst-content .admonition-todo .admonition-title, .rst-content .wy-alert-warning.admonition .admonition-title {
+  background: #e6b800;
+}
+.wy-alert.wy-alert-warning, .rst-content .wy-alert-warning.note, .rst-content .attention, .rst-content .caution, .rst-content .wy-alert-warning.danger, .rst-content .wy-alert-warning.error, .rst-content .wy-alert-warning.hint, .rst-content .wy-alert-warning.important, .rst-content .wy-alert-warning.tip, .rst-content .warning, .rst-content .wy-alert-warning.seealso, .rst-content .admonition-todo, .rst-content .wy-alert-warning.admonition {
+  background: #FcFde6;
+}

docs/conf.py

@@ -0,0 +1,187 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- PHP highlighting ---------------------------------------------------------
+#see: https://www.sitepoint.com/using-sphinx-for-php-project-documentation/
+
+from sphinx.highlighting import lexers
+from pygments.lexers.web import PhpLexer
+lexers["php"] = PhpLexer(startinline=True, linenos=1)
+lexers["php-annotations"] = PhpLexer(startinline=True, linenos=1)
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = u'Tripal BLAST'
+copyright = u'2018, University of Saskatchewan with the Legume Federation'
+author = u'University of Saskatchewan with the Legume Federation'
+
+# The short X.Y version
+version = u''
+# The full version, including alpha/beta/rc tags
+release = u''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Override the base theme.
+# We add the stylesheet this way so that it's loaded after the default.css
+# See https://docs.readthedocs.io/en/latest/guides/adding-custom-css.html
+def setup(app):
+    app.add_stylesheet('theme_overrides.css');
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'TripalBLASTdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'TripalBLAST.tex', u'Tripal BLAST Documentation',
+     u'University of Saskatchewan with the Legume Federation', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'tripalblast', u'Tripal BLAST Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'TripalBLAST', u'Tripal BLAST Documentation',
+     author, 'TripalBLAST', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']

docs/dev_guide.rst

@@ -0,0 +1,12 @@
+
+Developer Guide
+================
+
+A guide for module developers on how to customize and/or extend Tripal BLAST UI.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   dev_guide/custom_linkouts
+   dev_guide/custom_styling.rst

docs/dev_guide/custom_linkouts.rst

@@ -0,0 +1,90 @@
+Custom Link-outs
+=================
+
+In Tripal BLAST "Linkouts" refer to changing the hit name in the BLAST results table to a link. This link usually gives the user additional information and may link to pages in your Tripal site, external websites or genome browsers. You can configure link-outs per BLAST Database and depending on the type, many link-outs support regular expression for extracting parts of the name. The types provided by Tripal BLAST also require you select a Tripal Database (Tripal > Chado Modules > Databases) which contains the URL information for the link. If the link-out types supplied by Tripal BLAST do not fit your needs you can create a custom type using the documentation below.
+
+To create custom link-outs for Tripal BLAST you need to first create your own Drupal module. If you are unfamiliar with this process there are a number of good tutorial available in addition to the Drupal Documentation.
+
+Once you have a custom module you need to implement hook_blast_linkout_info() to tell Tripal BLAST about your custom link-out. You do this by creating a function with the name of your module replacing the word "hook". For example:
+
+.. code:: php
+
+  /**
+   * Implements hook_blast_linkout_info().
+   * Provides a custom link-out type for my institutes genome browser.
+   */
+  function mymodule_blast_linkout_info() {
+    $types = array();
+
+    $types['mybrowser'] = array(
+      // Human-readable Type name to display to users in the BLAST Database
+      // create/edit form.
+      'name' => 'UofS Browser',
+      // The function used to generate the URL to be linked to.
+      // This function will have full access to the blast hit and database
+      // prefix information and is expected to return a URL.
+      'process function' => 'mymodule_generate_linkout_mybrowser',
+      // Help text to show in the BLAST Database create/edit form so that
+      // users will know how to use this link-out type. Specifically, info
+      // about your assumptions for the URL prefix are very helpful.
+      // HTML is aloud but do not enclose in <p>.
+      'help' => 'This type assumes your blast database is the reference for one
+        of the University of Saskatchewan Genome Browsers and that you have selected
+        the Tripal Database referencing that browser below.',
+      // Whether or not the link-out requires additional fields from the nodes.
+      'require_regex' => TRUE,
+      'require_db' => TRUE,
+    );
+
+    return $types;
+  }
+
+Next you need to implement the process function that you indicated. This function is given a number of variables providing information about the hit, etc. and is expected to generate a fully rendered link based on that information. For example,
+
+.. code:: php
+
+  /**
+   * Generate a link to the UofS Genome Browser for a given hit.
+   *
+   * @param $url_prefix
+   *   The URL prefix for the BLAST Database queried.
+   * @param $hit
+   *   The blast XML hit object. This object has the following keys based on the
+   *   XML: Hit_num, Hit_id, Hit_def, Hit_accession, Hit_len and Hit_hsps.
+   *   Furthermore, a linkout_id key has beek added that contains the part of the
+   *   Hit_def extracted using a regex provided when the blastdb node was created.
+   * @param $info
+   *   Additional information that may be useful in creating a link-out. Includes:
+   *    - query_name: the name of the query sequence.
+   *    - score: the score of the blast hit.
+   *    - e-value: the e-value of the blast hit.
+   * @param $options
+   *   Any additional options needed to determine the type of link-out. None are
+   *   supported by this particular link-out type.
+   *
+   * @return
+   *   An html link.
+   */
+  function tripal_blast_generate_linkout_link($url_prefix, $hit, $info, $options = array()) {
+
+    if (isset($hit->{'linkout_id'})) {
+
+      // This is where you would generate your link. If your link requires query parameters
+      // then we suggest you use l() $options['query'] to encode them rather than appending
+      // them to the URL prefix directly.
+      // This StackExchange question shows a good example:
+      //   http://drupal.stackexchange.com/questions/38663/how-to-add-additional-url-parameters
+      $hit_url = $url_prefix . $hit->{'linkout_id'};
+
+      // See the documentation for l():
+      //  https://api.drupal.org/api/drupal/includes%21common.inc/function/l/7
+      return l(
+        $hit->{'linkout_id'},
+        $hit_url,
+        array('attributes' => array('target' => '_blank'))
+      );
+    }
+    else {
+      return FALSE;
+    }
+  }

docs/dev_guide/custom_styling.rst

@@ -0,0 +1,6 @@
+Custom Styling
+===============
+
+The BLAST module forms can be styled using CSS stylesheets in your own theme. By default it will use the default form themeing provided by your particular Drupal site allowing it to feel consistent with the look-and-feel of your Tripal site without customization being needed.
+
+Additionally, the results page, waiting pages and the alignment section of the results page have their own template files (``blast_report.tpl.php``, ``blast_report_pending.tpl.php``, and ``blast_report_alignment_row.tpl.php``, respectively) which can easily be overridden in your own theme providing complete control over the look of the BLAST results.

docs/index.rst

@@ -0,0 +1,10 @@
+
+Tripal BLAST Documentation!
+===========================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   user_guide
+   dev_guide

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/user_guide.rst

@@ -0,0 +1,19 @@
+User's Guide
+=============
+
+This module provides a basic interface to allow your users to utilize your server's NCBI BLAST+.
+
+Specifically it provides blast program-specific forms (blastn, blastp, tblastn, blastx are supported). In the future, there will be a single form where you will be able to select either a nucleotide or a protein database to BLAST against regardless of the type of query and it will decide which BLAST program to use based on the combination of query/database type (ie: if you selected a protein database on the nucleotide BLAST form then blastx would be used).
+
+BLAST submissions result in the creation of Tripal jobs which then need to run from the command-line. This ensures that long running BLASTs will not cause page time-outs but does add some management overhead and might result in longer waits for users depending on how often you have cron set to run Tripal jobs. You can alternatively use the Tripal Jobs Daemon to automate running of Tripal Jobs reducing user wait time and your own workload.
+
+The BLAST results page is an expandable summary table with each hit being listed as a row in the table with query/hit/e-value information. The row can then be expanded to include additional information including the alignment. Download formats are allow users to download these results in the familiar tabular, GFF3 or HTML NCBI formats.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   user_guide/features
+   user_guide/install
+   user_guide/targetdbs
+   user_guide/cvitjs

docs/user_guide/cvitjs.rst

@@ -0,0 +1,53 @@
+
+Whole Genome BLAST Hit Visualization (CViTjs)
+=============================================
+
+1. `Download CViTjs <https://github.com/LegumeFederation/cvitjs>`_ and copy the code to your webserver. It needs to be placed in ``[your drupal root]/sites/all/libraries``. To download, execute the git command inside the ``libraries/`` directory:
+
+.. code:: bash
+
+  git clone https://github.com/LegumeFederation/cvitjs.git
+
+2. CViTjs will have a config file in its root directory named ``cvit.conf``. This file provides information for whole genome visualization for each genome BLAST target. Make sure the config file can be edited by your web server.
+3. Enable CViTjs from the BLAST module administration page.
+4. Edit the configuration file to define each genome target. These will look like:
+
+.. code:: yaml
+
+  [data.Cajanus cajan - genome]
+  conf = data/cajca/cajca.conf
+  defaultData = data/cajca/cajca.gff
+
+Where:
+
+ - the section name, "data.Cajanus cajan - genome", consists of "data." followed by the name of the BLAST target node,
+ - the file "cajca.conf" is a cvit configuration file which describes how to draw the chromosomes and BLAST hits on the Cajanus cajan genome,
+ - and the file "cajca.gff" is a GFF3 file that describes the Cajanus cajan chromosomes.
+
+At the top of the configuration file there must be a [general] section that defines the default data set. For example:
+
+.. code:: yaml
+
+    [general]
+    data_default = data.Cajanus cajan - genome
+
+5. Edit the nodes for each genome target (nodes of type "BLAST Database") and enable whole genome visualization. Remember that the names listed in the CViTjs config file must match the BLAST node name. In the example above, the BLAST database node for the Cajanus cajan genome assembly is named "Cajanus cajan - genome"
+
+Notes
+------
+
+- The .conf file for each genome can be modified to suit your needs and tastes. See the sample configuration file, data/test1/test1.conf, and the `CViTjs documentation <https://github.com/LegumeFederation/cvitjs#using-cvitjs>`_.
+- Each blast target CViTjs configuration file must define how to visualize blast hits or you will not see them.
+
+.. code:: yaml
+
+  [blast]
+  feature = BLASTRESULT:match_part
+  glyph   = position
+  shape = rect
+  color   = #FF00FF
+  width = 5
+
+
+- You will have to put the target-specific conf and gff files (e.g. ``cajca.conf`` and ``cjca.gff``) on your web server, in the directory, ``sites/all/libraries/cvitjs/data``. You may choose to group files for each genome into subdirectories, for example, ``sites/all/libraries/cvitjs/data/cajca``.
+- It is important to make sure that ``cvit.conf`` points to the correct data directory and the correct ``.gff`` and ``.conf`` files for the genome in question. For more information about how to create the ``.gff`` file, see the `documentation <https://github.com/LegumeFederation/cvitjs#how-to>`_.

docs/user_guide/features.rst

@@ -0,0 +1,12 @@
+
+Highlighted Functionality
+==========================
+
+ - Supports blastn, blastp, tblastn, and blastx with separate forms depending upon the query type.
+ - Simple interface allowing users to paste or upload a query sequence and then select from available databases. Additionally, a FASTA file can be uploaded for use as a database to BLAST against.
+ - Tabular Results listing with alignment information and multiple download formats (HTML, TSV, GFF3, XML) available.
+ - Completely integrated with Tripal Jobs providing administrators with a way to track BLAST jobs and ensuring long running BLASTs will not cause page time-outs
+ - BLAST databases are made available to the module by creating Drupal Pages describing them. This allows administrators to use the Drupal Field API to add any information they want to these pages and to control which databases are available to a given user based on native Drupal permissions.
+ - BLAST database records can be linked to an external source with more information (ie: NCBI) per BLAST database.
+ - Per Query result diagrams visualizing the HSPs to help users better evaluate hit quality.
+ - Optional Whole Genome diagrams visualizing the distribution of hits which are configurable per Blast Database.

docs/user_guide/install.rst

@@ -0,0 +1,50 @@
+
+Installation
+=============
+
+QuickStart
+-----------
+1. Install NCBI BLAST+ on your server (Tested with 2.2.26+). There is a package available for Ubuntu to ease installation.
+2. Install this module as you would any Drupal module (ie: download, unpack in ``sites/all/modules`` and enable through ``http://[your site]/admin/modules``)
+3. Create "Blast Database" nodes for each dataset you want to make available for your users to BLAST against. BLAST databases should first be created using the command-line ``makeblastdb`` program with the ``-parse_seqids`` flag.
+4. It's recommended that you also install the Tripal Job Daemon to manage BLAST jobs and ensure they are run soon after being submitted by the user. Without this additional module, administrators will have to execute the tripal jobs either manually or through use of cron jobs.
+
+Install NCBI BLAST+
+--------------------
+
+See `NCBI's Standalone BLAST Setup for Unix <https://www.ncbi.nlm.nih.gov/books/NBK52640/>`_ for extended instructions.
+
+Install Tripal BLAST
+---------------------
+
+This module is available as a project on Drupal.org. As such, the preferred method of installation is using Drush:
+
+.. code:: bash
+
+  cd /var/www/html
+  drush pm-download tripal_blast libraries
+
+The above command downloads the module into the expected directory (e.g. ``/var/www/html/sites/all/modules/tripal_blast``). Next we need to install the module:
+
+.. code:: bash
+
+  drush pm-enable blast_ui
+
+Now that the module is installed, we just need to configure it!
+
+Configure Tripal BLAST
+-----------------------
+
+Navigate to Administration Toolbar > Modules and scroll down to BLAST UI (under "Tripal Extensions"). Then click on the configure link as shown below:
+
+.. image:: install.1.configure_link.png
+
+This will take you to the Tripal BLAST configuration form. The only required settings is the "path of the BLAST program". This should be set to the absolute path to the blastn executable and should include the final slash but not the program itself (e.g. ``/usr/bin/``).
+
+.. image:: install.2.configurepage.png
+
+The remaining configuration options allow you to customize Tripal BLAST UI to your own specific needs. For example, you can use the options under "Allow file upload" to allow users to allow FASTA files for either the query and/or the target database. Additionally, you can set the example sequences, protect against large jobs by limiting the number of results and/or add a warning to the top of the blast form.
+
+Don't forget to click the "Save Configuration" button at the bottom of the page to ensure your changes are saved!
+
+.. image:: install.3.savebutton.png

docs/user_guide/targetdbs.rst

@@ -0,0 +1,22 @@
+Blast Target Databases
+=======================
+
+"Target Database" is the BLAST terminology for a database you want your users to be able to BLAST against. For example, on the NCBI Blast website they have a nucleotide and protein target database.
+
+Add BLAST Database
+-------------------
+
+To add one to the "BLAST Databases" drop-down on the Blast program forms, in the "Navigation" menu go to "Add Content" > "Blast Database". Then fill out the form with the human readable name of your blast database (shown to the user in the drop-down) and the path to the blast database (passed to NCBI Blast).
+
+.. image:: targetdbs.1.nodeform.png
+
+For example, the above form will add "Tripalus Databasica Genome v1.0" to the "BLAST Databases" drop-down on the Nucleotide BLAST (blastn) form.
+
+Linkouts
+--------
+
+These settings will be used to transform the hit name into a link to additional information. The linkout type determines how the URL will be formed:
+
+ - **Generic Link**: Creates a generic link using a Tripal External Database and the backbone names from the blast database.
+ - **GBrowse Link**: Creates a link to highlight blast results on an existing GBrowse. This requires the blast database consist of backbone sequences of the same name and version as the GBrowse instance.
+ - **JBrowse Link**: Creates a link to highlight blast results on an existing JBrowse. This requires the blast database consist of backbone sequences of the same name and version as the JBrowse instance.