work in progress: revamping documentation

.gitignore

@@ -66,3 +66,4 @@ neo/test/io/neurosharemergeio.py
 files_for_testing_neo
 /venv
 /neo/test/resources
+doc/source/auto_examples

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/

doc/source/_static/css/custom.css

@@ -0,0 +1,85 @@
+.red {
+    color: red;
+}
+
+body {
+    border: 0;
+    background-color: rgb(168, 207, 157);
+}
+
+div.document {
+    background-image: none;
+    background-repeat: none;
+}
+
+div.footer {
+    padding-top: 20px;
+    background-color: rgb(168, 207, 157);
+}
+
+.wrapper {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    gap: 0px;
+    grid-auto-rows: minmax(200px, auto);
+    background-color: rgb(168, 207, 157);
+    border: 0;
+}
+.hero {
+    grid-column: 1 / 4;
+    grid-row: 1 / 3;
+    background-color: rgb(231, 242, 229);
+    margin-top: 80px;
+    margin-left: 10px;
+    margin-right: 10px;
+    margin-bottom: 80px;
+    padding: 20px 80px 20px 80px;
+    border-radius: 25px;
+    font-size: larger;
+}
+.infobox {
+    background-color: rgb(231, 242, 229);
+    padding: 10% 20% 10px 20%;
+    margin: 10px;
+    border-radius: 25px;
+    text-align: center;
+}
+.infobox h2 {
+    vertical-align: middle;
+}
+.grid1 {
+    grid-column: 1;
+    grid-row: 3;
+}
+.grid2 {
+    grid-column: 2;
+    grid-row: 3;
+}
+.grid3 {
+    grid-column: 3;
+    grid-row: 3;
+}
+.grid4 {
+    grid-column: 1;
+    grid-row: 4;
+}
+.grid5 {
+    grid-column: 2;
+    grid-row: 4;
+}
+.grid6 {
+    grid-column: 3;
+    grid-row: 4;
+}
+.grid7 {
+    grid-column: 1;
+    grid-row: 5;
+}
+.grid8 {
+    grid-column: 2;
+    grid-row: 5;
+}
+.grid9 {
+    grid-column: 3;
+    grid-row: 5;
+}

doc/source/_templates/index.html

@@ -0,0 +1,82 @@
+{%- extends "layout.html" %}
+
+{%- block relbar1 %}{% endblock %}
+{%- block content %}
+    <div class="document">
+
+        <div class="wrapper">
+            <div class="hero">
+                <img src="_static/neologo.png" alt="Neo logo" />
+
+                <p>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 and Igor Pro,
+                    and for writing to open formats such as NWB and NIX.</p>
+                <p>Neo implements a hierarchical data model well adapted to intracellular and
+                    extracellular electrophysiology and EEG data.
+                   Neo objects behave just like normal NumPy arrays, but with additional metadata,
+                    checks for dimensional consistency and automatic unit conversion.</p>
+                <p>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 represention of data, with no functions for data
+                    analysis or visualization.</p>
+            </div>
+            <div class="infobox grid1">
+                <a href="install.html">
+                    <h2>Download and install Neo</h2>
+                </a>
+            </div>
+            <div class="infobox grid2">
+                <a href="read_and_analyze.html">
+                    <h2>Read and analyze my data with Neo</h2>
+                </a>
+            </div>
+
+            <div class="infobox grid3">
+                <a href="share_data.html">
+                    <h2>Share my data in an open format</h2>
+                </a>
+            </div>
+
+            <div class="infobox grid4">
+                <a href="use_neo_as_dependency.html">
+                    <h2>Use Neo in my own library or app</h2>
+                </a>
+            </div>
+
+            <div class="infobox grid5">
+                <a href="add_file_format.html">
+                    <h2>Add support for a new file format</h2>
+                </a>
+            </div>
+
+            <div class="infobox grid6">
+                <a href="contributing.html">
+                    <h2>Contribute to Neo development</h2>
+                </a>
+            </div>
+
+            <div class="infobox grid7">
+                <a href="bug_reports.html">
+                    <h2>Report a bug</h2>
+                </a>
+            </div>
+
+            <div class="infobox grid8">
+                <a href="neo_users.html">
+                    <h2>See who else is using Neo</h2>
+                </a>
+            </div>
+
+            <div class="infobox grid9">
+                <a href="api_reference.html">
+                    <h2>API Reference</h2>
+                </a>
+            </div>
+
+        </div>
+
+    </div>
+{%- endblock %}
+{%- block relbar2 %}{% endblock %}

doc/source/add_file_format.rst

@@ -0,0 +1,13 @@
+====================================
+Adding support for a new file format
+====================================
+
+.. options - direct IO or RawIO
+
+.. mention possibility of connecting directly to a DB
+
+.. provide test files
+
+.. pull request - link to `contributing`
+
+.. pull in content from io_developers_guide

doc/source/api_reference.rst

@@ -1,3 +1,4 @@
+=============
 API Reference
 =============
 

doc/source/bug_reports.rst

@@ -0,0 +1,16 @@
+==============
+Reporting bugs
+==============
+
+
+Searching the issue tracker
+===========================
+
+
+Writing an informative bug report
+=================================
+
+
+
+Suggesting an improvement or a new feature
+==========================================