From eb22cb3935bec6b92698b14748d8ff6f3683c010 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jaquier=20Aur=C3=A9lien=20Tristan?= Date: Fri, 23 Jun 2023 15:48:30 +0200 Subject: [PATCH] use sphinx theme and README in documentation --- README.rst | 13 +++++- docs/source/api.rst | 8 +++- docs/source/bluepyefe.formats.igorpy.rst | 10 ----- docs/source/bluepyefe.formats.rst | 53 ------------------------ docs/source/bluepyefe.rst | 46 -------------------- docs/source/bluepyefe.tools.rst | 22 ---------- docs/source/conf.py | 14 +++++-- docs/source/index.rst | 35 +++------------- docs/source/installation.rst | 4 -- docs/source/modules.rst | 7 ---- tox.ini | 17 ++++---- 11 files changed, 44 insertions(+), 185 deletions(-) delete mode 100644 docs/source/bluepyefe.formats.igorpy.rst delete mode 100644 docs/source/bluepyefe.formats.rst delete mode 100644 docs/source/bluepyefe.rst delete mode 100644 docs/source/bluepyefe.tools.rst delete mode 100644 docs/source/installation.rst delete mode 100644 docs/source/modules.rst diff --git a/README.rst b/README.rst index e25bf5c..61757ae 100644 --- a/README.rst +++ b/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 `_ @@ -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 `_. 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 diff --git a/docs/source/api.rst b/docs/source/api.rst index 1845e61..d19fbf5 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -5,5 +5,9 @@ Python API ========== -.. toctree:: - :maxdepth: 3 +.. autosummary:: + :nosignatures: + :toctree: _autosummary + :recursive: + + bluepyefe diff --git a/docs/source/bluepyefe.formats.igorpy.rst b/docs/source/bluepyefe.formats.igorpy.rst deleted file mode 100644 index 9383fd3..0000000 --- a/docs/source/bluepyefe.formats.igorpy.rst +++ /dev/null @@ -1,10 +0,0 @@ -bluepyefe.formats.igorpy package -================================ - -Module contents ---------------- - -.. automodule:: bluepyefe.formats.igorpy - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/bluepyefe.formats.rst b/docs/source/bluepyefe.formats.rst deleted file mode 100644 index 9b92c55..0000000 --- a/docs/source/bluepyefe.formats.rst +++ /dev/null @@ -1,53 +0,0 @@ -bluepyefe.formats package -========================= - -Subpackages ------------ - -.. toctree:: - - bluepyefe.formats.igorpy - -Submodules ----------- - -bluepyefe.formats.axon module ------------------------------ - -.. automodule:: bluepyefe.formats.axon - :members: - :undoc-members: - :show-inheritance: - -bluepyefe.formats.csv\_lccr module ----------------------------------- - -.. automodule:: bluepyefe.formats.csv_lccr - :members: - :undoc-members: - :show-inheritance: - -bluepyefe.formats.ibf\_json module ----------------------------------- - -.. automodule:: bluepyefe.formats.ibf_json - :members: - :undoc-members: - :show-inheritance: - -bluepyefe.formats.igor module ------------------------------ - -.. automodule:: bluepyefe.formats.igor - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: bluepyefe.formats - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/bluepyefe.rst b/docs/source/bluepyefe.rst deleted file mode 100644 index f9e62cb..0000000 --- a/docs/source/bluepyefe.rst +++ /dev/null @@ -1,46 +0,0 @@ -bluepyefe package -================= - -Subpackages ------------ - -.. toctree:: - - bluepyefe.formats - bluepyefe.tools - -Submodules ----------- - -bluepyefe.extra module ----------------------- - -.. automodule:: bluepyefe.extra - :members: - :undoc-members: - :show-inheritance: - -bluepyefe.extractor module --------------------------- - -.. automodule:: bluepyefe.extractor - :members: - :undoc-members: - :show-inheritance: - -bluepyefe.plottools module --------------------------- - -.. automodule:: bluepyefe.plottools - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: bluepyefe - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/bluepyefe.tools.rst b/docs/source/bluepyefe.tools.rst deleted file mode 100644 index 940e371..0000000 --- a/docs/source/bluepyefe.tools.rst +++ /dev/null @@ -1,22 +0,0 @@ -bluepyefe.tools package -======================= - -Submodules ----------- - -bluepyefe.tools.tools module ----------------------------- - -.. automodule:: bluepyefe.tools.tools - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: bluepyefe.tools - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/conf.py b/docs/source/conf.py index 46a3a03..f65f9a4 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index a961c37..9758fd3 100644 --- a/docs/source/index.rst +++ b/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 + api.rst +.. |banner| image:: /logo/BluePyEfeBanner.jpg diff --git a/docs/source/installation.rst b/docs/source/installation.rst deleted file mode 100644 index 9af010c..0000000 --- a/docs/source/installation.rst +++ /dev/null @@ -1,4 +0,0 @@ -Installation -============ - -pip install bluepyefe diff --git a/docs/source/modules.rst b/docs/source/modules.rst deleted file mode 100644 index b1fbfae..0000000 --- a/docs/source/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -bluepyefe -========= - -.. toctree:: - :maxdepth: 4 - - bluepyefe diff --git a/tox.ini b/tox.ini index 0c35b1d..59e9ebb 100644 --- a/tox.ini +++ b/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 \ No newline at end of file