Merge pull request NeuralEnsemble#1178 from NeuralEnsemble/new-docs

First draft of proposal for documentation rewrite

.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_about.json

@@ -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/source/examples.rst → doc/old_stuffs/examples.rst

@@ -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/old_stuffs/index.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

doc/old_stuffs/install.rst

@@ -0,0 +1,81 @@
+************
+Installation
+************
+
+Neo is a pure Python package, so it should be easy to get it running on any
+system.
+
+Installing from the Python Package Index
+========================================
+
+Dependencies
+------------
+
+    * Python_ >= 3.7
+    * numpy_ >= 1.18.5
+    * quantities_ >= 0.12.1
+
+You can install the latest published version of Neo and its dependencies using::
+
+    $ pip install neo
+
+Certain IO modules have additional dependencies. If these are not satisfied,
+Neo will still install but the IO module that uses them will fail on loading:
+
+   * scipy >= 1.0.0 for NeoMatlabIO
+   * h5py >= 2.5 for KwikIO
+   * klusta for KwikIO
+   * igor >= 0.2 for IgorIO
+   * nixio >= 1.5 for NixIO
+   * stfio for StimfitIO
+   * pillow for TiffIO
+
+These dependencies can be installed by specifying a comma-separated list with the
+``pip install`` command::
+
+    $ pip install neo[nixio,tiffio]
+
+Or when installing a specific version of neo::
+
+    $ pip install neo[nixio,tiffio]==0.9.0
+
+These additional dependencies for IO modules are available::
+
+  * igorproio
+  * kwikio
+  * neomatlabio
+  * nixio
+  * stimfitio
+  * tiffio
+
+
+To download and install the package manually, download:
+
+    |neo_github_url|
+
+
+Then:
+
+.. parsed-literal::
+
+    $ unzip neo-|release|.zip
+    $ cd neo-|release|
+    $ python setup.py install
+
+
+Installing from source
+======================
+
+To install the latest version of Neo from the Git repository::
+
+    $ git clone git://github.com/NeuralEnsemble/python-neo.git
+    $ cd python-neo
+    $ python setup.py install
+
+
+.. _`Python`: https://www.python.org/
+.. _`numpy`: https://numpy.org/
+.. _`quantities`: https://pypi.org/project/quantities/
+.. _`pip`: https://pypi.org/project/pip/
+.. _`setuptools`: http://pypi.python.org/pypi/setuptools
+.. _Anaconda: https://www.anaconda.com/distribution/