[Bug] Docs fail to build with provided dependencies and raise weird issues

[morales-gregorio]

Describe the bug
The current explanation on how to build the documentation raises errors

To Reproduce
Following the instructions from the contribution guide

pip install -r requirements/requirements-docs.txt
pip install -r requirements/requirements-tutorials.txt
cd doc
export PYTHONPATH=${PYTHONPATH}.:../..
make html

This raises a number of issues because a number of dependencies are missing. One should probably use requirements/environment-docs.yml to build the environment, which is not clear from the guide.

Besides the errors about missing dependencies I get these issues on unchanged files which should be fine (mostly referencing the copyright notice in the docs):

/home/morales/git/forks/elephant_gc/doc/../elephant/phase_analysis.py:docstring of elephant.phase_analysis.weighted_phase_lag_index:22: ERROR: Unexpected indentation.
/home/morales/git/forks/elephant_gc/doc/../elephant/phase_analysis.py:docstring of elephant.phase_analysis.weighted_phase_lag_index:53: WARNING: Bullet list ends without a blank line; unexpected unindent.
/home/morales/git/forks/elephant_gc/doc/../elephant/spectral.py:docstring of elephant.spectral.multitaper_cross_spectrum:32: ERROR: Unexpected indentation.
/home/morales/git/forks/elephant_gc/doc/../elephant/spectral.py:docstring of elephant.spectral.multitaper_cross_spectrum:28: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/morales/git/forks/elephant_gc/doc/../elephant/spectral.py:docstring of elephant.spectral.multitaper_cross_spectrum:35: ERROR: Unexpected indentation.
/home/morales/git/forks/elephant_gc/doc/../elephant/spectral.py:docstring of elephant.spectral.multitaper_cross_spectrum:31: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/morales/git/forks/elephant_gc/doc/../elephant/spectral.py:docstring of elephant.spectral.segmented_multitaper_cross_spectrum:67: ERROR: Unexpected indentation.
/home/morales/git/forks/elephant_gc/doc/../elephant/spectral.py:docstring of elephant.spectral.segmented_multitaper_cross_spectrum:63: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/morales/git/forks/elephant_gc/doc/../elephant/spectral.py:docstring of elephant.spectral.segmented_multitaper_cross_spectrum:70: ERROR: Unexpected indentation.
/home/morales/git/forks/elephant_gc/doc/../elephant/spectral.py:docstring of elephant.spectral.segmented_multitaper_cross_spectrum:66: WARNING: Block quote ends without a blank line; unexpected unindent.

[Moritz-Alexander-Kern]

Hey @morales-gregorio ,

thanks to your detailed report, I was able to reproduce this in the following way:

conda create --name elephant_doctest python=3.9
conda activate elephant_doctest

pip install -r requirements/requirements-docs.txt
pip install -r requirements/requirements-tutorials.txt

cd doc
export PYTHONPATH=${PYTHONPATH}.:../..
make html

I get the following:

Notebook error:
CellExecutionError in tutorials/granger_causality.ipynb:
------------------
import matplotlib.pyplot as plt
import numpy as np
from elephant.causality.granger import pairwise_granger, conditional_granger
------------------

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
Cell In[1], line 3
      1 import matplotlib.pyplot as plt
      2 import numpy as np
----> 3 from elephant.causality.granger import pairwise_granger, conditional_granger

File ~/git/INM-6/elephant/elephant/__init__.py:9
      1 # -*- coding: utf-8 -*-
      2 """
      3 Elephant is a package for the analysis of neurophysiology data, based on Neo.
      4 
      5 :copyright: Copyright 2014-2023 by the Elephant team, see `doc/authors.rst`.
      6 :license: Modified BSD, see LICENSE.txt for details.
      7 """
----> 9 from . import (statistics,
     10                spike_train_generation,
     11                spike_train_synchrony,
     12                spike_train_correlation,
     13                unitary_event_analysis,
     14                cubic,
     15                spectral,
     16                kernels,
     17                spike_train_dissimilarity,
     18                spike_train_surrogates,
     19                signal_processing,
     20                current_source_density,
     21                change_point_detection,
     22                phase_analysis,
     23                sta,
     24                conversion,
     25                neo_tools,
     26                cell_assembly_detection,
     27                spade,
     28                waveform_features,
     29                gpfa)
     31 # not included modules on purpose:
     32 #   parallel: avoid warns when elephant is imported
     34 try:

File ~/git/INM-6/elephant/elephant/statistics.py:70
     67 import math
     68 import warnings
---> 70 import neo
     71 from neo.core.spiketrainlist import SpikeTrainList
     72 import numpy as np

ModuleNotFoundError: No module named 'neo'
ModuleNotFoundError: No module named 'neo'

You can ignore this error by setting the following in conf.py:

    nbsphinx_allow_errors = True

make: *** [Makefile:45: html] Error 2

For the complete output, see: output.txt

Workaround (?)

Add the missing dependencies manually

pip install -e .[extras]
pip install -r requirements/requirements-docs.txt
pip install -r requirements/requirements-tutorials.txt
pip install viziphant
pip install mpi4py

cd doc
make html

Suggested Fixes

• update the requirements-docs.txt and requirements-tutorials.txt files
• update the contribution guide in the documentation
• fix the indentation and formatting issues similar to Fix/docstring warnings #478 (e.g. ERROR: Unexpected indentation, WARNING: Bullet list ends without a blank line; unexpected unindent.)