Documentation overhaul

afqbrowser/__init__.py

@@ -1 +1,2 @@
 from .browser import *  # noqa
+from .gh_pages import *  # noqa

doc/api.rst

@@ -8,10 +8,9 @@ Python Functions
    :template: function.rst
    :toctree: gen_api
 
-   afqbrowser.mat2tables
    afqbrowser.assemble
    afqbrowser.run
-
+   afqbrowser.upload
 
 
 JavaScript API

doc/binder_integration.rst

@@ -0,0 +1,28 @@
+.. _binder_integration:
+
+Integration of ``AFQ-Browser`` and ``Binder``
+=============================================
+
+To facilitate further computations on data-sets published using
+``AFQ-Browser``, we integrate data-sets that are published on GitHub (see :ref:`usage_guide`) with the `Binder <https://mybinder.org/>`_ service.
+
+Binder makes the contents of a GitHub repository available through a
+`Jupyter <jupyter.org>`_ computational notebook interface. This means that
+visitors to a published ``AFQ-Browser`` instance can start computing on the
+data immediately without having to download the data, or install any software.
+
+.. note:: For further information about Binder, please read about recent
+  developments in this project in `this blog post <https://elifesciences.org/labs/8653a61d/introducing-binder-2-0-share-your-interactive-research-environment>`_.
+
+
+Software available on Binder
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Binder environment automatically provisioned for ``AFQ-Browser`` instances
+has `scikit-learn <http://scikit-learn.org/>`_,
+`pandas <https://pandas.pydata.org>`_ and
+`seaborn <https://seaborn.pydata.org/>`_
+installed into it.
+
+To add more software dependencies, you will need to edit the
+``requirements.txt`` file in the GitHub (for example, see `this file <https://github.com/yeatmanlab/Sarica_2017/blob/gh-pages/requirements.txt>`_), `before` launching Binder for the first time from your instance.

doc/dataformat.rst

@@ -1,3 +1,5 @@
+.. _dataformat:
+
 
 The AFQ-Browser data format
 ============================

doc/getting_help.rst

@@ -1,5 +1,8 @@
+.. _getting_help:
 
-Help using `afqbrowser`
-========================
+Getting more help
+==================
 
-If you run into issues using ``AFQ-Browser`` feel free to post an issue on our GitHub repository: ` https://github.com/yeatmanlab/AFQ-Browser/issues <https://github.com/yeatmanlab/AFQ-Browser/issues>`_, or to get in touch via our mailing list: `[email protected] <mailto:[email protected]>`_.
+If you run into issues using ``AFQ-Browser`` feel free to post an issue on our
+GitHub repository: `https://github.com/yeatmanlab/AFQ-Browser/issues <https://github.com/yeatmanlab/AFQ-Browser/issues>`_, or to get in touch via
+our mailing list: `[email protected] <mailto:[email protected]>`_.

doc/index.rst

@@ -1,3 +1,5 @@
+.. _home:
+
 .. figure:: _static/BDE_Banner_revised20160211-01.jpg
    :align: center
    :figclass: align-center
@@ -22,28 +24,31 @@ major fiber tracts in individual human brains, and quantification of the
 tissue properties within the tracts (`Yeatman et al. 2012 <http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0049790>`_).
 
 This software package allows researchers to interactively query the data
-processed with `AFQ` to explore patterns in the data.
+processed with `AFQ` (or other similar software) to explore patterns in the
+data.
 
 AFQ-Browser paper
 ~~~~~~~~~~~~~~~~~
 
 If you are interested in technical details and motivation behind this project, please read our `paper <http://www.biorxiv.org/content/early/2017/08/30/182402>`_.
 
+Acknowledgements
+~~~~~~~~~~~~~~~~~~~
+
+this work was supported by a grant from the `Gordon & Betty Moore Foundation <https://www.moore.org/>`_,  and from the `Alfred P. Sloan Foundation <http://www.sloan.org/>`_ to the `University of Washington eScience Institute <http://escience.washington.edu/>`_.
 
+Documentation
+~~~~~~~~~~~~~~~~~
     .. toctree::
        :maxdepth: 2
 
        installation_guide
        usage_guide
-       reference/index
-       api
-       dataformat
        getting_help
+       dataformat
+       long_term_preservation
+       binder_integration
+       api
 
 
-   Acknowledgements: this work was supported by a grant from the
-   `Gordon & Betty Moore Foundation <https://www.moore.org/>`_,  and from the
-   `Alfred P. Sloan Foundation <http://www.sloan.org/>`_ to the
-   `University of Washington eScience Institute <http://escience.washington.edu/>`_.
-
 .. _AFQ: http://github.com/yeatmanlab/AFQ

doc/installation_guide.rst

@@ -1,12 +1,14 @@
+.. _installation_guide:
 
-Installing `afqbrowser`
-========================
+
+Installing ``AFQ-Browser``
+==========================
 
 Installing the release version
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The released version of the software is the one that is officially supported,
-and if you are getting started with afqbrowser, this is probably where you
+and if you are getting started with ``AFQ-Browser``, this is probably where you
 should get started
 
 AFQ-browser depends on numpy_, pandas_ and scipy_. The `publish` mechanisms also

doc/long_term_preservation.rst

@@ -0,0 +1,31 @@
+.. _long_term_preservation:
+
+Long-term data preservation
+===========================
+
+GitHub is great, but long-term preservation of data stored on GitHub is not
+guaranteed. To promote long-term preservation of data from instances of
+``AFQ-Browser``, and eventual integration across data-sets
+we record data published through ``AFQ-Browser`` (see :ref:`usage_guide`) in
+`AFQ Vault <http://afqvault.org>`_, a centralized data-base of ``AFQ-Browser``
+instances.
+
+In addition, we recommend that users of the software create a digital object
+identifier for their instance of ``AFQ-Browser``. One great way to do that uses
+Zenodo (see below).
+
+
+Using Zenodo for long-term data preservation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`Zenodo <http://zenodo.org/>`_ is as service developed by `CERN <https://home.cern/>`_ to provide a platform for open and sustainable science
+(see `About Zenodo <http://about.zenodo.org/>`_ for more details).
+
+To create a digital object identifier (DOI) for your GitHub-published
+instance of ``AFQ-Browser`` `join Zenodo <https://zenodo.org/signup/>`_ with
+your GitHub account. After you do that, you can deposit the GitHub repository
+that holds your instance of ``AFQ-Browser`` by following these steps:
+
+#. Flip the switch for your repo on `Zenodo's GitHub settings page <https://zenodo.org/account/settings/github/>`_
+
+#. Create a release in the GitHub repo containing your instance of ``AFQ-Browser``. See `this page <https://help.github.com/articles/creating-releases/>`_ for instructions.

doc/usage_guide.rst

@@ -1,30 +1,53 @@
+.. _usage_guide:
 
-Using `afqbrowser`
-========================
+Creating and publishing an ``AFQ-Browser`` instance
+===================================================
 
-After installing the software, you can run the program on mat files generated by
-AFQ_ (and other tractography software). For an example, download this `mat file <https://github.com/yeatmanlab/AFQ-Browser/raw/master/afqbrowser/site/client/data/afq.mat>`_, change your working directory to the location where the file was
-downloaded to, or move the file to your current working directory and run::
+After :ref:`installation_guide`, you can run the program on mat files generated
+by AFQ_ or on the ``stats`` directory created by TRACULA (or data from other tractometry software formatted according to :ref:`dataformat`).
+For an example, download this `mat file <https://github.com/yeatmanlab/AFQ-Browser/raw/master/afqbrowser/site/client/data/afq.mat>`_, and run::
+
+    afqbrowser-assemble /path/to/afq.mat
+
+You will be prompted to provide a title for the page, as well as a sub-title,
+and you can add links from both of these (we use these links to refer back to
+the paper describing the dataset, see
+`this site <https://yeatmanlab.github.io/Sarica_2017>`_ for an example). This
+will create a folder called ``AFQ-browser`` in your current file-system
+location, containing the materials for your `AFQ-Browser` instance
+(alternatively, use the ``-t`` flag to provide another file-system location as a
+target).
+
+To view the assembled website, run::
 
-    afqbrowser-assemble afq.mat
     afqbrowser-run
 
-Open a browser pointing to `http://localhost:8080 <http://localhost:80080>`_ ,
-to view the visualization of these data and to interact with it. The variables in the metadata table are created based on the variables that are stored in the `mat file <https://github.com/yeatmanlab/AFQ/wiki#including-subject-metadata-in-the-afq-structure>`_ of the afq.mat file.
+Per default, this will look for the instance of `AFQ-Browser` in your current
+file-system location (provide another target using the ``-t`` flag). Open a
+browser pointing to `http://localhost:8080 <http://localhost:8080>`_ ,
+to view the visualization of these data and to interact with it (another port
+can be set using the ``-p`` flag). The variables in the metadata table are
+created based on the variables that are stored in the `mat file <https://github.com/yeatmanlab/AFQ/wiki#including-subject-metadata-in-the-afq-structure>`_ of the afq.mat file.
+
+
+.. note:: `Binder <https://mybinder.org/>`_ integration (see :ref:`binder_integration`) will not work if you are running your instance locally. To activate Binder integration you must publish your instance to GitHub (see below).
 
 Publishing your website
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-There is a command line function that allows you to publish your website to
-GitHub. If you don't already have one, start by `creating a GitHub account <https://github.com/join>`_. Then run the following sequence::
+To publish your website to GitHub you will need a GitHub account. If you don't
+already have one, start by `creating a GitHub account <https://github.com/join>`_. Then run the following sequence::
 
-    afqbrowser-assemble   # Run this if you haven't before
-    afqbrowser-publish -t ./AFQ-Browser -r myresults
+    afqbrowser-assemble   # Run this only if you haven't before
+    afqbrowser-publish /path/to/target/ reponame
 
-Where ``./AFQ-Browser`` is the folder that was created by ``afqbrowser-assemble``,
-and the URL of the website is: `https://username.github.io/myresults` (with
-`username` replaced with your GitHub username, and `myresults` replaced with the
-input to the ``-r`` flag).
+Where ``/path/to/target`` points to the folder that was created by
+``afqbrowser-assemble``, and ``reponame`` will be used to create the URL of the
+website. You will be prompted for your GitHub user-name and password, and the
+URL will be `https://username.github.io/reponame`. If you also provide an
+input to the optional ``-o`` flag with the name of a `GitHub organization <https://github.com/blog/674-introducing-organizations>`_ that you are a member
+of (and are allowed to create new repositories for!), the website URL will be:
+`https://orgname.github.io/reponame`.
 
 If you use two-factor authentication to access GitHub, you'll need to
 `create a personal access token <https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/>`_
@@ -33,5 +56,8 @@ place. ``afqbrowser-publish`` will ask you for this token to login to GitHub.
 Leave the password field blank to tell ``afqbrowser-publish`` to give you a
 prompt for your token.
 
+.. note:: When you publish an ``AFQ-Browser`` instance to GitHub, we also
+  record your website in `AFQ Vault <http://afqvault.org>`_.
+  See :ref:`long_term_preservation`.
 
 .. _AFQ: https://github.com/yeatmanlab/AFQ