Merge pull request #41 from neuromusic/feature/docs

documentation tooling
AllenInstitute · Nov 19, 2017 · e737a55 · e737a55
2 parents b20ee5c + e26168a
commit e737a55
Show file tree

Hide file tree

Showing 25 changed files with 497 additions and 72 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -31,7 +31,7 @@ jobs:
       # Download and cache dependencies
       - restore_cache:
           keys:
-          - py35-dependencies-{{ checksum "requirements.txt" }}
+          - py35-dependencies-{{ checksum "requirements.txt" }}-{{ checksum "requirements-dev.txt"}}
           # fallback to using the latest cache if no exact match is found
           - py35-dependencies-
 
@@ -40,13 +40,13 @@ jobs:
           command: |
             python3 -m venv venv
             . venv/bin/activate
-            pip install -r requirements.txt
+            pip install -r requirements-dev.txt
             pip install git+https://github.com/j-friedrich/OASIS.git
 
       - save_cache:
           paths:
             - ./venv
-          key: py35-dependencies-{{ checksum "requirements.txt" }}
+          key: py35-dependencies-{{ checksum "requirements.txt" }}-{{ checksum "requirements-dev.txt"}}
 
       # run tests!
       - run:
@@ -86,7 +86,7 @@ jobs:
           command: |
             virtualenv venv
             . venv/bin/activate
-            pip install -r requirements.txt
+            pip install -r requirements-dev.txt
             pip install git+https://github.com/j-friedrich/OASIS.git
 
       - save_cache:

diff --git a/.gitignore b/.gitignore
@@ -67,6 +67,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/generated/
+docs/gallery/
 
 # PyBuilder
 target/
@@ -105,4 +107,4 @@ ENV/
 .mypy_cache/
 
 # Visual Studio Code
-.vscode/
+.vscode/
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -5,9 +5,11 @@ Credits
 Development Lead
 ----------------
 
-* Justin Kiggens <[email protected]>
+* Justin Kiggins <[email protected]>
 
 Contributors
 ------------
 
 * Nicholas Cain <[email protected]>
+* Michael Oliver <[email protected]>
+* Sahar Manavi <[email protected]>
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -79,7 +79,7 @@ Ready to contribute? Here's how to set up `neuroglia` for local development.
 5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
 
     $ flake8 neuroglia tests
-    $ python setup.py test or py.test
+    $ py.test
     $ tox
 
    To get flake8 and tox, just pip install them into your conda env.
@@ -101,8 +101,8 @@ Before you submit a pull request, check that it meets these guidelines:
 2. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring, and add the
    feature to the list in README.rst.
-3. The pull request should work for Python 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check
-   https://travis-ci.org/AllenInstitute/neuroglia/pull_requests
+3. The pull request should work for Python 2.7 and 3.5. Check
+   https://circleci.com/gh/AllenInstitute/neuroglia
    and make sure that the tests pass for all supported Python versions.
 
 Tips

diff --git a/HISTORY.rst b/HISTORY.rst
diff --git a/README.rst b/README.rst
@@ -3,20 +3,21 @@
 neuroglia
 =========
 
+more than just glue. scikit-learn compatible transformers for neural data science
+
 .. image:: https://circleci.com/gh/AllenInstitute/neuroglia.svg?style=svg&circle-token=d0a164bbf19524a24f0d6bc42535aab9c89f8c13
     :target: https://circleci.com/gh/AllenInstitute/neuroglia
 
+
 What is neuroglia?
 ------------------
 
-scikit-learn compatible transformers for neurophysiology data
-
 Things you can do:
 
 - make a PSTH
-- extract events from a calcium signal
-- synthesize a calcium signal
 - infer spikes from a calcium signal
+- smooth a spiketrain
+- chain these things together into scikit-learn pipelines
 
 Installation
 ------------
@@ -30,12 +31,17 @@ Requirements
 -  scikit-learn
 -  xarray
 
-## Level of Support
-We are planning on occasional updating this tool with no fixed schedule. Community involvement is encouraged through both issues and pull requests.  Please make pull requests against the dev branch, as we will test changes there before merging into master.
+Level of Support
+------------
+We are planning on occasional updating this tool with no fixed schedule. Community involvement is encouraged through both issues and pull requests.
+
+License
+-------
 
-## License
+TBD
 
 
-## Authors
+Authors
+--------
 
 .. include:: ../AUTHORS.rst
diff --git a/docs/Makefile b/docs/Makefile
@@ -54,6 +54,11 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,56 @@
+.. _api_ref:
+
+.. currentmodule:: neuroglia
+
+API reference
+=============
+
+.. _spike_api:
+
+Spike transformers
+------------------
+
+.. autosummary::
+   :toctree: generated/
+
+    spike.Binner
+    spike.Smoother
+    nwb.SpikeTablizer
+
+.. _trace_api:
+
+Trace transformers
+------------------
+
+.. autosummary::
+   :toctree: generated/
+
+    trace.Binarizer
+    trace.EdgeDetector
+    trace.WhenTrueFinder
+    calcium.OASISInferer
+    calcium.MedianFilterDetrend
+    calcium.SavGolFilterDetrend
+    calcium.EventRescale
+
+
+.. _event_api:
+
+Event transformers
+------------------
+
+.. autosummary::
+   :toctree: generated/
+
+    event.PeriEventSpikeSampler
+    event.PeriEventTraceSampler
+
+.. _tensor_api:
+
+Tensor transformers
+-------------------
+
+.. autosummary::
+   :toctree: generated/
+
+    tensor.ResponseReducer
diff --git a/docs/authors.rst b/docs/authors.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -32,6 +32,7 @@
 sys.path.insert(0, project_root)
 
 import neuroglia
+import sphinx_bootstrap_theme
 
 # -- General configuration ---------------------------------------------
 
@@ -40,7 +41,14 @@
 
 # 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',
+    'sphinx.ext.autosummary',
+    # 'numpydoc',
+    'sphinx.ext.napoleon',
+    'sphinx_gallery.gen_gallery',
+    ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -56,7 +64,7 @@
 
 # General information about the project.
 project = u'neuroglia'
-copyright = u"2017, Nicholas Cain"
+copyright = u"2017, Allen Institute for Brain Science"
 
 # The version info for the project you're documenting, acts as replacement
 # for |version| and |release|, also used in various other places throughout
@@ -106,17 +114,50 @@
 # documents.
 #keep_warnings = False
 
+sphinx_gallery_conf = {
+    # path to your examples scripts
+    'examples_dirs': '../examples',
+    # path where to save gallery generated examples
+    'gallery_dirs': 'gallery',
+    # #directory where function granular galleries are stored
+    'backreferences_dir': 'generated',
+    #
+    # # Modules for which function level galleries are created.  In
+    # # this case sphinx_gallery and numpy in a tuple of strings.
+    # 'doc_module': ('neuroglia',),
+    'download_section_examples': False,
+    'default_thumb_file': '/local1/astrocytes-jsnyder.jpg',
+    'min_reported_time': 10,
+    }
+
 
 # -- 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 = 'default'
+# html_theme = 'alabaster'
+html_theme = 'bootstrap'
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
 # 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 = {}
+
+html_theme_options = {
+    'source_link_position': "footer",
+    'bootswatch_theme': "yeti", # https://bootswatch.com/
+    'navbar_sidebarrel': False,
+    'bootstrap_version': "3",
+    'navbar_links': [
+                     ("Introduction", "introduction"),
+                     ("Examples",'examples'),
+                     ("API", "api"),
+                     ],
+
+    }
+
+
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -153,7 +194,7 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+# html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names
 # to template names.
@@ -190,6 +231,7 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'neurogliadoc'
 
+autosummary_generate = True
 
 # -- Options for LaTeX output ------------------------------------------
 
@@ -210,7 +252,7 @@
 latex_documents = [
     ('index', 'neuroglia.tex',
      u'neuroglia Documentation',
-     u'Nicholas Cain', 'manual'),
+     u'Justin Kiggins', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at
@@ -241,7 +283,7 @@
 man_pages = [
     ('index', 'neuroglia',
      u'neuroglia Documentation',
-     [u'Nicholas Cain'], 1)
+     [u'Justin Kiggins'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -256,7 +298,7 @@
 texinfo_documents = [
     ('index', 'neuroglia',
      u'neuroglia Documentation',
-     u'Nicholas Cain',
+     u'Justin Kiggins',
      'neuroglia',
      'One line description of project.',
      'Miscellaneous'),

diff --git a/docs/contributing.rst b/docs/contributing.rst
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,3 @@
+.. _examples:
+
+.. include:: gallery/index.rst
diff --git a/docs/history.rst b/docs/history.rst