Merge pull request #1178 from NeuralEnsemble/new-docs

First draft of proposal for documentation rewrite

Author: JuliaSprenger

.gitignore

@@ -66,3 +66,11 @@ neo/test/io/neurosharemergeio.py
 files_for_testing_neo
 /venv
 /neo/test/resources
+doc/examples
+doc/*.abf
+doc/*.png
+doc/*.plx
+doc/*.nev
+doc/*.ns5
+doc/*.nix
+doc/*.nwb

README.rst

@@ -45,7 +45,7 @@ More information
 ----------------
 
 - Home page: http://neuralensemble.org/neo
-- Mailing list: https://groups.google.com/forum/?fromgroups#!forum/neuralensemble
+- Mailing list: http://neuralensemble.org/community
 - Documentation: http://neo.readthedocs.io/
 - Bug reports: https://github.com/NeuralEnsemble/python-neo/issues
 
@@ -74,7 +74,7 @@ No. 785907 (Human Brain Project SGA2) and No. 945539 (Human Brain Project SGA3).
 .. _NiBabel: http://nipy.sourceforge.net/nibabel/
 .. _PyNN: http://neuralensemble.org/PyNN
 .. _quantities: http://pypi.python.org/pypi/quantities
-.. _`NeuralEnsemble mailing list`: http://groups.google.com/group/neuralensemble
+.. _`NeuralEnsemble mailing list`: http://neuralensemble.org/community
 .. _`issue tracker`: https://github.c
 .. _tridesclous: https://github.com/tridesclous/tridesclous
 .. _ephyviewer: https://github.com/NeuralEnsemble/ephyviewer

doc/Makefile

@@ -29,6 +29,7 @@ help:
 
 clean:
 	-rm -rf $(BUILDDIR)/*
+	-rm -rf source/examples
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

doc/example_data.txt

@@ -0,0 +1,13 @@
+{
+    "filename": "example_data.txt",
+    "delimiter": " ",
+    "timecolumn": null,
+    "units": "mV",
+    "time_units": "ms",
+    "sampling_rate": {
+        "value": 1.0,
+        "units": "kHz"
+    },
+    "method": "genfromtxt",
+    "signal_group_mode": "all-in-one"
+}

doc/example_data_about.json

@@ -15,5 +15,4 @@ A set of examples in :file:`neo/examples/` illustrates the use of Neo classes.
 
 .. literalinclude:: ../../examples/read_files_neo_rawio.py
 
-.. literalinclude:: ../../examples/simple_plot_with_matplotlib.py
-
+.. literalinclude:: ../../examples/plot_with_matplotlib.py

doc/source/core.rst doc/old_stuffs/core.rstdoc/source/core.rst renamed to doc/old_stuffs/core.rst

@@ -0,0 +1,92 @@
+.. module:: neo
+
+.. image:: images/neologo.png
+    :width: 600 px
+
+Neo is a Python package for working with electrophysiology data in Python, together
+with support for reading a wide range of neurophysiology file formats, including
+Spike2, NeuroExplorer, AlphaOmega, Axon, Blackrock, Plexon, Tdt, Igor Pro, and support for
+writing to a subset of these formats plus non-proprietary formats including Kwik and HDF5.
+
+The goal of Neo is to improve interoperability between Python tools for
+analyzing, visualizing and generating electrophysiology data, by providing a common,
+shared object model. In order to be as lightweight a dependency as possible,
+Neo is deliberately limited to representation of data, with no functions for data
+analysis or visualization.
+
+Neo is used by a number of other software tools, including
+SpykeViewer_ (data analysis and visualization), Elephant_ (data analysis),
+the G-node_ suite (databasing), PyNN_ (simulations), tridesclous_ (spike sorting)
+and ephyviewer_ (data visualization).
+OpenElectrophy_ (data analysis and visualization) used an older version of Neo.
+
+
+Neo implements a hierarchical data model well adapted to intracellular and
+extracellular electrophysiology and EEG data with support for multi-electrodes
+(for example tetrodes). Neo's data objects build on the quantities_ package,
+which in turn builds on NumPy by adding support for physical dimensions. Thus
+Neo objects behave just like normal NumPy arrays, but with additional metadata,
+checks for dimensional consistency and automatic unit conversion.
+
+A project with similar aims but for neuroimaging file formats is `NiBabel`_.
+
+
+Documentation
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   install
+   core
+   usecases
+   io
+   rawio
+   examples
+   api_reference
+   whatisnew
+   developers_guide
+   io_developers_guide
+   authors
+
+
+License
+-------
+
+Neo is free software, distributed under a 3-clause Revised BSD license (BSD-3-Clause).
+
+
+Support
+-------
+
+If you have problems installing the software or questions about usage, documentation or anything
+else related to Neo, you can post to the `NeuralEnsemble mailing list`_. If you find a bug,
+please create a ticket in our `issue tracker`_.
+
+
+Contributing
+------------
+
+Any feedback is gladly received and highly appreciated! Neo is a community project,
+and all contributions are welcomed - see the :doc:`developers_guide` for more information.
+`Source code <https://github.com/NeuralEnsemble/python-neo>`_ is on GitHub.
+
+
+Citation
+--------
+
+.. include:: ../../CITATION.txt
+
+
+.. _OpenElectrophy: https://github.com/OpenElectrophy/OpenElectrophy
+.. _Elephant: http://neuralensemble.org/elephant
+.. _G-node: http://www.g-node.org/
+.. _Neuroshare: http://neuroshare.org/
+.. _SpykeViewer: https://spyke-viewer.readthedocs.io/en/latest/
+.. _NiBabel: https://nipy.org/nibabel/
+.. _PyNN: http://neuralensemble.org/PyNN
+.. _quantities: https://pypi.org/project/quantities/
+.. _`NeuralEnsemble mailing list`: https://groups.google.com/forum/#!forum/neuralensemble
+.. _`issue tracker`: https://github.com/NeuralEnsemble/python-neo/issues
+.. _tridesclous: https://github.com/tridesclous/tridesclous
+.. _ephyviewer: https://github.com/NeuralEnsemble/ephyviewer