Merge pull request #152 from AurelienJaquier/docs

use sphinx theme and README in documentation

README.rst

@@ -102,7 +102,7 @@ To install BluePyEfe, run:
 
 
 Quick Start and Operating Principle
-===========
+===================================
 
 For a hands-on introduction to BluePyEfe, have a look at the notebook `examples/example_of_extraction.ipynb <examples/example_of_extraction.ipynb>`_
 
@@ -128,7 +128,7 @@ A pseudo-code for the main function of the package (bluepyefe.extract.extract_ef
 Each of these steps are parametrized by a number of settings, therefore we recommend that you read carefully the docstring of the function.
 
 Coming from the legacy version
-===============================
+==============================
 The legacy version (v0.4*) is moved to the legacy branch.
 Changes introduced in v2.0.0 are listed in the `CHANGELOG.rst <CHANGELOG.rst>`_. 
 That is the only file you need to look at for the changes as the future changes will also be noted there.
@@ -137,4 +137,13 @@ Funding
 =======
 This work has been partially funded by the European Union Seventh Framework Program (FP7/2007­2013) under grant agreement no. 604102 (HBP), and by the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreements No. 720270 (Human Brain Project SGA1) and No. 785907 (Human Brain Project SGA2) and by the EBRAINS research infrastructure, funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3).
 
+
+..
+    The following image is also defined in the index.rst file, as the relative path is 
+    different, depending from where it is sourced.
+    The following location is used for the github README
+    The index.rst location is used for the docs README; index.rst also defined an end-marker, 
+    to skip content after the marker 'substitutions'.
+
+.. substitutions
 .. |banner| image:: docs/source/logo/BluePyEfeBanner.jpg

docs/source/api.rst

@@ -5,5 +5,9 @@
 Python API
 ==========
 
-.. toctree::
-   :maxdepth: 3
+.. autosummary::
+   :nosignatures:
+   :toctree: _autosummary
+   :recursive:
+
+   bluepyefe

docs/source/conf.py

@@ -30,8 +30,11 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    "sphinx.ext.autosummary",
     'sphinx.ext.doctest',
-    'sphinx.ext.viewcode']
+    'sphinx.ext.viewcode',
+    "sphinx.ext.napoleon",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -47,7 +50,6 @@
 
 # General information about the project.
 project = u'BluePyEfe'
-copyright = u'2020, Blue Brain Project'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -102,7 +104,13 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx-bluebrain-theme'
+html_title = 'BluepyEfe'
+html_show_sourcelink = False
+html_theme_options = {
+    "repo_url": "https://github.com/BlueBrain/BluePyEfe/",
+    "repo_name": "BlueBrain/BluePyEfe"
+}
 
 # 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

docs/source/index.rst

@@ -1,35 +1,12 @@
-.. BluePyEfe documentation master file, created by
-   sphinx-quickstart on Mon Aug 26 16:33:43 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to BluePyEfe's documentation!
-=====================================
-
-BluePyEfe aims at easing the process of reading experimental recordings and
-extracting batches of electrical features from these recordings. To do so, it
-combines
-trace reading functions and features extraction functions from the eFel library.
-
-BluePyEfe outputs protocols and features files in the format used by BluePyOpt
-for neuron electrical model building.
-
-To get started, we recommend to have a look at the example located in the
-github directory of the repository.
-
-Contents:
+.. include:: ../../README.rst
+   :end-before: .. substitutions
 
 .. toctree::
+   :hidden:
    :maxdepth: 3
 
-   installation
-   api
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   Home <self>
+   api.rst
 
+.. |banner| image:: /logo/BluePyEfeBanner.jpg

tox.ini

@@ -11,7 +11,8 @@ python =
 
 [testenv]
 envdir =
-    py3{8,9,10,11,}{-functional,-notebooks,-style,-syntax,-docs,-upload_docs}: {toxworkdir}/py3
+    py3{8,9,10,11,}{-functional,-notebooks,-style,-syntax}: {toxworkdir}/py3
+    docs: {toxworkdir}/docs
 usedevelop = true
 deps =
     coverage
@@ -20,9 +21,6 @@ deps =
     pytest-xdist
     nbmake
     flake8
-    docs,upload_docs,firefox: sphinx
-    docs,upload_docs,firefox: sphinx-bluebrain-theme
-    upload_docs: docs-internal-upload>=0.0.8
 allowlist_externals =
     make
 passenv = https_proxy, USER, KRB5CCNAME
@@ -38,6 +36,11 @@ commands =
 
     notebooks: pytest -n=auto --nbmake "examples"
 
-    docs,upload_docs: sphinx-build -Q -b html -d {envtmpdir}/doctrees docs/source {envtmpdir}/html
-    upload_docs: python ./.upload_docs.py {envtmpdir}/html
-    upload_docs: docs-internal-upload --docs-path {envtmpdir}/html --use-major-minor-only --no-duplicate-version-error
+[testenv:docs]
+basepython = python3.9
+changedir = docs
+deps =
+    sphinx
+    sphinx-bluebrain-theme
+commands = make html SPHINXOPTS=-W
+allowlist_externals = make