Docs baby steps (#126)

Implement first documentation for memote.

docs/_static/my-styles.css

@@ -0,0 +1,43 @@
+#navbar.navbar.navbar-default.navbar-fixed-top {
+    background-color: #2A7BB8;
+}
+
+.navbar-brand {
+     padding: 10px 15px 15px 15px;
+}
+
+.navbar-default .navbar-nav>li>a {
+    color: #FFF;
+}
+
+.navbar-default .navbar-text {
+    color: #ACD7E6;
+}
+
+.form-control{
+    color: #FFF;
+}
+
+input.form-control{
+    text-color: #FFF;
+}
+
+.form-control::-webkit-input-placeholder {
+    color: #ACD7E6;
+}  /* WebKit, Blink, Edge */
+
+.form-control:-moz-placeholder {
+    color: #ACD7E6;
+}  /* Mozilla Firefox 4 to 18 */
+
+.form-control::-moz-placeholder {
+    color: #ACD7E6;
+}  /* Mozilla Firefox 19+ */
+
+.form-control:-ms-input-placeholder {
+    color: #ACD7E6;
+}  /* Internet Explorer 10-11 */
+
+.form-control::-ms-input-placeholder {
+    color: #ACD7E6;
+}  /* Microsoft Edge */

docs/_templates/layout.html

@@ -0,0 +1,5 @@
+{# Import the theme's layout. #}
+{% extends "!layout.html" %}
+
+{# Custom CSS overrides #}
+{% set css_files = css_files + ['_static/my-styles.css'] %}

docs/conf.py

@@ -16,6 +16,7 @@
 import os
 import sys
 
+import sphinx_bootstrap_theme
 import memote
 
 # If extensions (or modules to document with autodoc) are in another
@@ -41,7 +42,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.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'numpydoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -112,32 +113,35 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'bootstrap'
 
 # 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 = {}
+html_theme_options = {
+    'navbar_title':" ",
+    'bootswatch_theme': "paper"
+    }
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+html_title = "Memote"
 
 # A shorter title for the navigation bar.  Default is the same as
 # html_title.
-#html_short_title = None
+#html_short_title = "memote"
 
 # The name of an image file (relative to this directory) to place at the
 # top of the sidebar.
-#html_logo = None
+html_logo = "memote-logo.png"
 
 # The name of an image file (within the static path) to use as favicon
 # of the docs.  This file should be a Windows icon file (.ico) being
 # 16x16 or 32x32 pixels large.
-#html_favicon = None
+html_favicon = "memote-icon.ico"
 
 # Add any paths that contain custom static files (such as style sheets)
 # here, relative to this directory. They are copied after the builtin

docs/core.rst

@@ -0,0 +1,8 @@
+====
+Core
+====
+
+Basic
+-----
+
+.. automodule:: </source/tests/test_basic.py>

docs/flowchart.rst

@@ -0,0 +1,9 @@
+=========
+Flowchart
+=========
+
+This cheat-sheet flowchart servers as a visual guide on how to get up and
+running with memote! It is essentially the pictographic form of the section
+:doc:`Getting Started <getting_started>`.
+
+.. image:: MemoteFlowchart.png

docs/getting_started.rst

@@ -0,0 +1,130 @@
+.. highlight:: shell
+
+===============
+Getting Started
+===============
+
+After installation, memote can be employed in two different ways: As a
+benchmarking tool for ad hoc performance testing, and as a testing suite to aid
+with the reconstruction of metabolic models. When using memote to benchmark a
+model, the tests are run once and a report is generated which depicts the
+status-quo. Opposed to this, memote as a testing suite sets up a
+version-controlled repository, enables continuous integration via Travis CI and
+produces a performance report with each incremental change.
+
+Here, we explain step by step the necessary commands to pursue either workflow.
+Users that have already followed this tutorial once may want to refer to the
+:doc:`cheat-sheet flowchart <flowchart>` to refresh their memory.
+
+Benchmark
+---------
+
+Single Model
+^^^^^^^^^^^^
+
+To benchmark the performance of a single model, run this command in your
+terminal:
+
+.. code-block:: console
+
+    $ memote --model path/to/model.xml report --one-time
+
+This will generate the performance report as index.html
+
+The output filename can be changed by adding the following option.
+To illustrate here it is changed to 'report.html'.
+
+.. code-block:: console
+
+    $ memote --model path/to/model.xml report --one-time --filename "report.html"
+
+Comparative
+^^^^^^^^^^^
+
+Benchmarking one model against another is done by running the following
+command:
+
+.. code-block:: console
+
+    $ memote --model path/to/model.xml report --diff path/to/model2.xml
+
+Reconstruction
+--------------
+
+When starting a memote repository, users need to provide a SBMLv3-FBC formatted
+.xml file. Automatic draft reconstruction tools such as `Pathway Tools`_,
+`Model SEED`_, `The RAVEN Toolbox`_ and `others`_ are able to output files in
+this format. Model repositories such as `BiGG`_ or `BioModels`_ further serve
+as a great resource for models in the correct format.
+
+.. _Pathway Tools: http://bioinformatics.ai.sri.com/ptools/
+.. _Model SEED: http://modelseed.org
+.. _The RAVEN Toolbox: https://github.com/SysBioChalmers/RAVEN
+.. _others: http://www.secondarymetabolites.org/sysbio/
+.. _BiGG: http://bigg.ucsd.edu
+.. _BioModels: https://www.ebi.ac.uk/biomodels-main/
+
+With this in mind, starting a local, version-controlled model repository is as
+simple as running the following command:
+
+.. code-block:: console
+
+    $ memote new
+
+CI tested, online and public workflow:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After this, the user will be prompted with a few questions regarding details of
+the project. If the project is to be kept strictly locally, the user does
+not need to supply `GitHub`_ (or `GitLab`_ - not implemented yet) credentials.
+However, these are a requirement if the project is to use the full benefits of
+distributed version control such as cloud-based development, remote
+collaboration and community feedback. It is important to note that furthermore
+a public repository is needed to set up automatic testing through continuous
+integration, one of the key features of memote.
+
+Once all the questions following `memote new` have been answered, a public
+repository has been created under either the user's GitHub or GitLab account.
+To enable continuous integration via Travis CI the following command is
+executed:
+
+.. code-block:: console
+
+    $ memote online
+
+Now, after each edit to the model in the repository, the user can generate
+an update to the continuous model report shown at the project's gh-pages
+branch by saving the changes with the following command:
+
+.. code-block:: console
+
+    $ memote save
+
+For advanced users: `memote save` is the equivalent of executing `git add`,
+`git commit` and `git push` in sequence.
+
+Offline, local or private workflow:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Users that have decided to not to use `GitHub`_ (or `GitLab`_) or those that
+have decided to set the model repository to private, will need to execute:
+
+.. code-block:: console
+
+    $ memote
+
+to run the testing suite on their commit history followed by:
+
+.. code-block:: console
+
+    $ memote report
+
+to generate the same type of report that would be shown automatically with
+continuous integration. After this it is crucial to save the generated test
+results by running `memote save` again.
+
+We recommend the public workflow not only to promote open, collaborative
+science but also to benefit from the full functionality of memote.
+
+.. _GitHub: https://github.com
+.. _GitLab: https://gitlab.com

docs/index.rst

@@ -13,10 +13,14 @@ Contents:
 
    readme
    installation
+   getting_started
+   flowchart
    usage
    contributing
    authors
    history
+   memote_tests
+
 
 Indices and tables
 ==================

docs/memote.rst

@@ -0,0 +1,18 @@
+memote package
+==============
+
+Subpackages
+-----------
+
+.. toctree::
+
+    memote.suite
+    memote.support
+
+Module contents
+---------------
+
+.. automodule:: memote
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/memote.suite.collect.rst

@@ -0,0 +1,7 @@
+memote.suite.collect module
+===========================
+
+.. automodule:: memote.suite.collect
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/memote.suite.reporting.bag.rst

@@ -0,0 +1,7 @@
+memote.suite.reporting.bag module
+=================================
+
+.. automodule:: memote.suite.reporting.bag
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/memote.suite.reporting.plot.rst

@@ -0,0 +1,7 @@
+memote.suite.reporting.plot module
+==================================
+
+.. automodule:: memote.suite.reporting.plot
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/memote.suite.reporting.reports.basic_report.rst

@@ -0,0 +1,7 @@
+memote.suite.reporting.reports.basic_report module
+==================================================
+
+.. automodule:: memote.suite.reporting.reports.basic_report
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/memote.suite.reporting.reports.diff_report.rst

@@ -0,0 +1,7 @@
+memote.suite.reporting.reports.diff_report module
+=================================================
+
+.. automodule:: memote.suite.reporting.reports.diff_report
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/memote.suite.reporting.reports.history_report.rst

@@ -0,0 +1,7 @@
+memote.suite.reporting.reports.history_report module
+====================================================
+
+.. automodule:: memote.suite.reporting.reports.history_report
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/memote.suite.reporting.reports.report.rst

@@ -0,0 +1,7 @@
+memote.suite.reporting.reports.report module
+============================================
+
+.. automodule:: memote.suite.reporting.reports.report
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/memote.suite.reporting.reports.rst

@@ -0,0 +1,20 @@
+memote.suite.reporting.reports package
+======================================
+
+Submodules
+----------
+
+.. toctree::
+
+   memote.suite.reporting.reports.basic_report
+   memote.suite.reporting.reports.diff_report
+   memote.suite.reporting.reports.history_report
+   memote.suite.reporting.reports.report
+
+Module contents
+---------------
+
+.. automodule:: memote.suite.reporting.reports
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/memote.suite.reporting.rst

@@ -0,0 +1,25 @@
+memote.suite.reporting package
+==============================
+
+Subpackages
+-----------
+
+.. toctree::
+
+    memote.suite.reporting.reports
+
+Submodules
+----------
+
+.. toctree::
+
+   memote.suite.reporting.bag
+   memote.suite.reporting.plot
+
+Module contents
+---------------
+
+.. automodule:: memote.suite.reporting
+    :members:
+    :undoc-members:
+    :show-inheritance: