Update docs

nrdg · Jul 28, 2020 · 288e8aa · 288e8aa
1 parent cf84e31
commit 288e8aa
Show file tree

Hide file tree

Showing 16 changed files with 329 additions and 43 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,9 @@
 # setuptools_scm generated version file
 cloud_bids_layout/version.py
 
+# example dataset
+examples/ds000030
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

diff --git a/docs/_static/collapsible.css b/docs/_static/collapsible.css
@@ -0,0 +1,38 @@
+.toggle {
+    border: 1px solid black;
+    border-radius: 3px;
+}
+
+.toggle .header {
+    display: block;
+    clear: both;
+    padding: 5px;
+    background: gainsboro;
+}
+
+.toggle .content {
+    padding: 5px;
+}
+
+.toggle .header.open {
+    border-bottom: 1px solid black;
+    background: silver;
+}
+
+.toggle .header:hover {
+    background: silver;
+}
+
+.toggle .header:after {
+    content: "show ▼";
+    font-size: 75%;
+    text-align: right;
+    float:right;
+}
+
+.toggle .header.open:after {
+    content: "hide ▲";
+    font-size: 75%;
+    text-align: right;
+    float:right;
+}
diff --git a/docs/_static/git.png b/docs/_static/git.png
diff --git a/docs/_static/logo.png b/docs/_static/logo.png
diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
@@ -0,0 +1,9 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+.. raw:: html
+
+    <div style='clear:both'></div>
diff --git a/docs/_templates/autosummary/function.rst b/docs/_templates/autosummary/function.rst
@@ -0,0 +1,9 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}
+
+.. raw:: html
+
+    <div style='clear:both'></div>
diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst
@@ -0,0 +1,6 @@
+{{ fullname | escape | underline }}
+
+.. automodule:: {{ fullname }}
+
+   Members
+   =======
diff --git a/docs/_templates/page.html b/docs/_templates/page.html
@@ -0,0 +1,17 @@
+{% extends "!page.html" %}
+
+{% set css_files = css_files + ["_static/collapsible.css"] %}
+
+{% block footer %}
+    {{ super() }}
+    <script type="text/javascript">
+        $(document).ready(function() {
+            $(".toggle > *").hide();
+            $(".toggle .header").show();
+            $(".toggle .header").click(function() {
+                $(this).parent().children().not(".header").toggle(400);
+                $(this).parent().children(".header").toggleClass("open");
+            })
+        });
+    </script>
+{% endblock %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -45,6 +45,8 @@
 sys.path.append(os.path.abspath("sphinxext"))
 
 extensions = [
+    "nbsphinx",
+    "sphinx.ext.mathjax",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
@@ -55,9 +57,11 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "alabaster",
-    "github",
 ]
 
+nbsphinx_allow_errors = False
+nbsphinx_execute = "never"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -77,7 +81,7 @@
     # path where to save gallery generated examples
     "gallery_dirs": "auto_examples",
     # To auto-generate example sections in the API
-    "doc_module": ("cloudknot",),
+    "doc_module": ("cloud_bids_layout",),
     # Auto-generated mini-galleries go here
     "backreferences_dir": "gen_api",
 }

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -0,0 +1,16 @@
+.. _faq-label:
+
+Frequently Asked Questions
+==========================
+
+.. container:: toggle
+
+   .. container:: header
+
+      What is the airspeed velocity of an unladen swallow?
+
+   .. container:: content
+
+      Roughly 11 meters per second, or 24 miles per hour. See
+      `Style.org -- Estimating the Airspeed Velocity of an Unladen Swallow <http://style.org/unladenswallow/>`_.
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -4,20 +4,12 @@ Welcome to Cloud-BIDS-Layout's documentation!
 Cloud-BIDS-Layout is a lightweight wrapper for pybids' BIDS.Layout that
 can grab BIDS studies from Amazon S3.
 
-Usage
------
-
-.. code-block:: python
-
-   # Insert an amazing Cloud-BIDS-Layout example here
-   pass
-
 Motivation
 ----------
 
-The [Brain Imaging Data Structure (BIDS)](https://bids.neuroimaging.io/)
+The `Brain Imaging Data Structure (BIDS) <https://bids.neuroimaging.io/>`_
 is an intuitive, accessible, and community-driven data specification for
-neuroimaging data. [Pybids](https://bids-standard.github.io/pybids/)
+neuroimaging data. `Pybids <https://bids-standard.github.io/pybids/>`_
 is an exceptionally written Python library that makes it easy for
 researchers to query, summarize, and manipulate BIDS-compliant data.
 However, it's workhorse `BIDSLayout` class doesn't index remote datasets
@@ -29,35 +21,20 @@ supported but support for Google Cloud Storage and others is coming
 soon. Cloud-BIDS-Layout creates a lightweight semblance of the remote
 dataset, just enough to pass to pybids' `BIDSLayout` for indexing.
 The user can then use pybids' familiar `.get()` method to select a
-subset of the study that they wish to download to the host. See the
-[documentation](https://nrdg.github.io/cloud_bids_layout) for more
-details.
-
-`cottoncandy <https://doi.org/10.5281/zenodo.1034342>`_ for interacting with
-numpy array data on `Amazon S3 <https://aws.amazon.com/s3/>`_. Or see `pywren
-<http://pywren.io/>`_, which enables users to run their existing python code
-on `AWS Lambda <https://aws.amazon.com/lambda/>`_, providing convenient
-distributed execution for jobs that fall within the AWS Lambda limits (maximum
-300 seconds of execution time, 1.5 GB of RAM, 512 MB of local storage, and no
-root access). For jobs that require more, we introduce cloudknot to execute
-existing python code on AWS Batch.
-
-Cloudknot takes as input a python function, Dockerizes it for use in an Amazon
-ECS instance, and creates all the necessary AWS Batch constituent resources to
-submit jobs. You can then use cloudknot to submit and view jobs for a range
-of inputs.
-
-Installation and getting started
---------------------------------
+subset of the study that they wish to download to the host. See
+Usage_ for more details.
+
+Installation and usage
+----------------------
 
 To install Cloud-BIDS-Layout and see usage details
-visit :ref:`installation-label` and :ref:`usage-label`.
+visit :ref:`installation-label` and Usage_.
 
 Documentation and API
 ---------------------
 
 Most users will only need to interact with the `CloudBIDSLayout` class. See
-:ref:`usage-label` for more details.
+Usage_ for more details.
 
 Bugs and issues
 ---------------
@@ -98,10 +75,12 @@ support from the `Washington Research Foundation <http://www.wrfseattle.org/>`_
    :hidden:
 
    installation <installation>
-   usage <usage>
+   usage <usage.ipynb>
    faq <faq>
    examples <https://github.com/nrdg/cloud_bids_layout/tree/master/examples>
-   modules
    contributing <https://github.com/nrdg/cloud_bids_layout/blob/master/CONTRIBUTING.md>
    code <https://github.com/nrdg/cloud_bids_layout>
    bugs <https://github.com/nrdg/cloud_bids_layout/issues>
+   history <history>
+
+.. _Usage: usage.ipynb
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -1,4 +1,5 @@
 .. highlight:: shell
+.. _installation-label:
 
 ============
 Installation

diff --git a/docs/usage.ipynb b/docs/usage.ipynb
@@ -0,0 +1 @@
+../examples/usage.ipynb
diff --git a/docs/usage.rst b/docs/usage.rst