pandoc errors during tox -e docs

[dkrako]

          I have implemented an update to the contributing docs but I don't know in which way we prefer to install `pandoc`. For whatever reason if I run `tox -e docs` without manually installing `pandoc` (`pip install pandoc`) it errors locally for me 

          one solution would be to guide the people to manually install it, but this is kinda silly....

Originally posted by @SiQube in #543 (comment)

@SiQube can you post the error message?

[SiQube]

this is how I reproduced the error following the CONTRIBUTING.md.

dreich@MacBook-Pro-von-David /tmp % git clone [email protected]:aeye-lab/pymovements
Cloning into 'pymovements'...
remote: Enumerating objects: 3558, done.
remote: Counting objects: 100% (1445/1445), done.
remote: Compressing objects: 100% (584/584), done.
remote: Total 3558 (delta 1072), reused 1044 (delta 792), pack-reused 2113
Receiving objects: 100% (3558/3558), 1.01 MiB | 3.06 MiB/s, done.
Resolving deltas: 100% (2290/2290), done.
y%                                                                                                               


dreich@MacBook-Pro-von-David /tmp % cd pymovements 


dreich@MacBook-Pro-von-David pymovements % virtualenv venv
created virtual environment CPython3.8.18.final.0-64 in 159ms
  creator CPython3Posix(dest=/private/tmp/pymovements/venv, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/Users/dreich/Library/Application Support/virtualenv)
    added seed packages: pip==23.2.1, setuptools==68.1.2, wheel==0.41.2
  activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator


dreich@MacBook-Pro-von-David pymovements % . venv/bin/activate


(venv) dreich@MacBook-Pro-von-David pymovements % pip install tox
Collecting tox
  Obtaining dependency information for tox from https://files.pythonhosted.org/packages/f5/f9/963052e8b825645c54262dce7b7c88691505e3b9ee10a3e3667711eaaf21/tox-4.11.3-py3-none-any.whl.metadata
  Using cached tox-4.11.3-py3-none-any.whl.metadata (5.0 kB)
Collecting cachetools>=5.3.1 (from tox)
  Obtaining dependency information for cachetools>=5.3.1 from https://files.pythonhosted.org/packages/a9/c9/c8a7710f2cedcb1db9224fdd4d8307c9e48cbddc46c18b515fefc0f1abbe/cachetools-5.3.1-py3-none-any.whl.metadata
  Using cached cachetools-5.3.1-py3-none-any.whl.metadata (5.2 kB)
Collecting chardet>=5.2 (from tox)
  Obtaining dependency information for chardet>=5.2 from https://files.pythonhosted.org/packages/38/6f/f5fbc992a329ee4e0f288c1fe0e2ad9485ed064cac731ed2fe47dcc38cbf/chardet-5.2.0-py3-none-any.whl.metadata
  Using cached chardet-5.2.0-py3-none-any.whl.metadata (3.4 kB)
Collecting colorama>=0.4.6 (from tox)
  Using cached colorama-0.4.6-py2.py3-none-any.whl (25 kB)
Collecting filelock>=3.12.3 (from tox)
  Obtaining dependency information for filelock>=3.12.3 from https://files.pythonhosted.org/packages/5e/5d/97afbafd9d584ff1b45fcb354a479a3609bd97f912f8f1f6c563cb1fae21/filelock-3.12.4-py3-none-any.whl.metadata
  Downloading filelock-3.12.4-py3-none-any.whl.metadata (2.8 kB)
Collecting packaging>=23.1 (from tox)
  Using cached packaging-23.1-py3-none-any.whl (48 kB)
Collecting platformdirs>=3.10 (from tox)
  Obtaining dependency information for platformdirs>=3.10 from https://files.pythonhosted.org/packages/14/51/fe5a0d6ea589f0d4a1b97824fb518962ad48b27cd346dcdfa2405187997a/platformdirs-3.10.0-py3-none-any.whl.metadata
  Using cached platformdirs-3.10.0-py3-none-any.whl.metadata (11 kB)
Collecting pluggy>=1.3 (from tox)
  Obtaining dependency information for pluggy>=1.3 from https://files.pythonhosted.org/packages/05/b8/42ed91898d4784546c5f06c60506400548db3f7a4b3fb441cba4e5c17952/pluggy-1.3.0-py3-none-any.whl.metadata
  Using cached pluggy-1.3.0-py3-none-any.whl.metadata (4.3 kB)
Collecting pyproject-api>=1.6.1 (from tox)
  Obtaining dependency information for pyproject-api>=1.6.1 from https://files.pythonhosted.org/packages/cf/b4/39eea50542e50e93876ebc09c4349a9c9eee9f6b9c9d30f88c7dc5433db8/pyproject_api-1.6.1-py3-none-any.whl.metadata
  Using cached pyproject_api-1.6.1-py3-none-any.whl.metadata (2.8 kB)
Collecting tomli>=2.0.1 (from tox)
  Using cached tomli-2.0.1-py3-none-any.whl (12 kB)
Collecting virtualenv>=20.24.3 (from tox)
  Obtaining dependency information for virtualenv>=20.24.3 from https://files.pythonhosted.org/packages/4e/8b/f0d3a468c0186c603217a6656ea4f49259630e8ed99558501d92f6ff7dc3/virtualenv-20.24.5-py3-none-any.whl.metadata
  Using cached virtualenv-20.24.5-py3-none-any.whl.metadata (4.5 kB)
Collecting distlib<1,>=0.3.7 (from virtualenv>=20.24.3->tox)
  Obtaining dependency information for distlib<1,>=0.3.7 from https://files.pythonhosted.org/packages/43/a0/9ba967fdbd55293bacfc1507f58e316f740a3b231fc00e3d86dc39bc185a/distlib-0.3.7-py2.py3-none-any.whl.metadata
  Using cached distlib-0.3.7-py2.py3-none-any.whl.metadata (5.1 kB)
Using cached tox-4.11.3-py3-none-any.whl (153 kB)
Using cached cachetools-5.3.1-py3-none-any.whl (9.3 kB)
Using cached chardet-5.2.0-py3-none-any.whl (199 kB)
Downloading filelock-3.12.4-py3-none-any.whl (11 kB)
Using cached platformdirs-3.10.0-py3-none-any.whl (17 kB)
Using cached pluggy-1.3.0-py3-none-any.whl (18 kB)
Using cached pyproject_api-1.6.1-py3-none-any.whl (12 kB)
Using cached virtualenv-20.24.5-py3-none-any.whl (3.7 MB)
Using cached distlib-0.3.7-py2.py3-none-any.whl (468 kB)
Installing collected packages: distlib, tomli, pluggy, platformdirs, packaging, filelock, colorama, chardet, cachetools, virtualenv, pyproject-api, tox
Successfully installed cachetools-5.3.1 chardet-5.2.0 colorama-0.4.6 distlib-0.3.7 filelock-3.12.4 packaging-23.1 platformdirs-3.10.0 pluggy-1.3.0 pyproject-api-1.6.1 tomli-2.0.1 tox-4.11.3 virtualenv-20.24.5


(venv) dreich@MacBook-Pro-von-David pymovements % tox -e docs
docs: install_deps> python -I -m pip install '.[docs]'
.pkg: install_requires> python -I -m pip install 'setuptools-git-versioning<2' 'setuptools>=42' 'versioneer[toml]<1.0,>=0.29' wheel
.pkg: _optional_hooks> python /private/tmp/pymovements/venv/lib/python3.8/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: get_requires_for_build_sdist> python /private/tmp/pymovements/venv/lib/python3.8/site-packages/pyproject_api/_backend.py True setuptools.build_meta
.pkg: build_sdist> python /private/tmp/pymovements/venv/lib/python3.8/site-packages/pyproject_api/_backend.py True setuptools.build_meta
docs: install_package_deps> python -I -m pip install 'matplotlib<4,>=3.0.0' 'numpy<2,>=1.10.0' 'pandas<3,>1.0.0' 'polars<0.20.0,>=0.19.0' 'pyarrow<14,>=11.0.0' 'scipy<2,>=1.5.4' 'tqdm<5,>=4.0.0'
docs: install_package> python -I -m pip install --force-reinstall --no-deps /private/tmp/pymovements/.tox/.tmp/package/1/pymovements-0.16.1.post17+git.097cbbb9.tar.gz
docs: commands[0]> sphinx-build --color -W --keep-going -d /private/tmp/pymovements/docs/doctree -b html /private/tmp/pymovements/docs/source /private/tmp/pymovements/docs/build
Running Sphinx v7.1.2
initializing sphinxcontrib.datatemplates
making output directory... done
checking bibtex cache... out of date
parsing bibtex file /private/tmp/pymovements/docs/source/bibliography.bib... parsed 7 entries
[autosummary] generating autosummary for: advanced-installation.rst, bibliography.rst, getting-started.rst, index.rst, reference/index.rst, tutorials/R-tutorial.md, tutorials/detecting-events.ipynb, tutorials/event-properties.ipynb, tutorials/heatmap.ipynb, tutorials/index.rst, tutorials/local-dataset.ipynb, tutorials/plot-main-sequence.ipynb, tutorials/preprocessing-raw-data.ipynb, tutorials/public-datasets.ipynb, tutorials/pymovements-in-10-minutes.ipynb, tutorials/saving-loading-events.ipynb, tutorials/saving-loading-preprocessed.ipynb
[autosummary] generating autosummary for: /private/tmp/pymovements/docs/source/reference/pymovements.dataset.rst, /private/tmp/pymovements/docs/source/reference/pymovements.datasets.rst, /private/tmp/pymovements/docs/source/reference/pymovements.events.rst, /private/tmp/pymovements/docs/source/reference/pymovements.gaze.rst, /private/tmp/pymovements/docs/source/reference/pymovements.plotting.rst, /private/tmp/pymovements/docs/source/reference/pymovements.synthetic.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.rst
[autosummary] generating autosummary for: /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.DatasetDefinition.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.DatasetLibrary.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.DatasetPaths.rst, /private/tmp/pymovements/docs/source/reference/pymovements.datasets.GazeBase.rst, /private/tmp/pymovements/docs/source/reference/pymovements.datasets.GazeBaseVR.rst, /private/tmp/pymovements/docs/source/reference/pymovements.datasets.JuDo1000.rst, /private/tmp/pymovements/docs/source/reference/pymovements.datasets.ToyDataset.rst, /private/tmp/pymovements/docs/source/reference/pymovements.datasets.ToyDatasetEyeLink.rst, /private/tmp/pymovements/docs/source/reference/pymovements.events.EventDataFrame.rst, ..., /private/tmp/pymovements/docs/source/reference/pymovements.plotting.traceplot.rst, /private/tmp/pymovements/docs/source/reference/pymovements.plotting.tsplot.rst, /private/tmp/pymovements/docs/source/reference/pymovements.synthetic.step_function.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.archives.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.checks.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.decorators.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.downloads.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.filters.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.parsing.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.paths.rst
[autosummary] generating autosummary for: /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.__init__.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.clear_events.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.compute_event_properties.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.compute_properties.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.detect.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.detect_events.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.download.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.extract.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.load.rst, /private/tmp/pymovements/docs/source/reference/pymovements.dataset.Dataset.load_event_files.rst, ..., /private/tmp/pymovements/docs/source/reference/pymovements.utils.downloads.download_and_extract_archive.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.downloads.download_file.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.filters.events_split_nans.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.filters.filter_candidates_remove_nans.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.parsing.check_nan.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.parsing.compile_patterns.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.parsing.get_additional_columns.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.parsing.parse_eyelink.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.paths.get_filepaths.rst, /private/tmp/pymovements/docs/source/reference/pymovements.utils.paths.match_filepaths.rst
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 17 source files that are out of date
updating environment: [new config] 145 added, 0 changed, 0 removed
reading sources... [ 93%] tutorials/detecting-events
Notebook error:
PandocMissing in tutorials/detecting-events.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html
docs: exit 2 (22.37 seconds) /private/tmp/pymovements> sphinx-build --color -W --keep-going -d /private/tmp/pymovements/docs/doctree -b html /private/tmp/pymovements/docs/source /private/tmp/pymovements/docs/build pid=3377
.pkg: _exit> python /private/tmp/pymovements/venv/lib/python3.8/site-packages/pyproject_api/_backend.py True setuptools.build_meta
  docs: FAIL code 2 (51.01=setup[28.64]+cmd[22.37] seconds)
  evaluation failed :( (51.15 seconds)

using pip install -e . does not change anything here :( it seems like the optional dependencies are not picked up...

[SiQube]

I've researched some more and apparently you need a local installation of pandoc to fix this, see here. I added a sentence to CONTRIBUTING.md in PR #574