search

pydata / pydata-sphinx-theme

A clean, three-column Sphinx theme with Bootstrap for the PyData community
https://pydata-sphinx-theme.readthedocs.io
BSD 3-Clause "New" or "Revised" License
616 stars 319 forks source link

DOC - contribution setup guidelines need improvement #1987

Open kaycebasques opened 1 month ago

kaycebasques commented 1 month ago

Hi, I hit some friction when setting up my local development environment on Debian-based gLinux. I used the Get started guide.

# easier for me to do everything from virtual env. not really discussed in the guide.
python3 -m venv venv
source venv/bin/activate
python3 -m pip install tox
python -m pip install pre-commit
# installing pandoc over pip didn't work. had to install system-wide.
sudo apt install pandoc
# ditto.
python3 -m pip install graphviz
# got some warnings-as-errors about files already existing in _build, see below.
rm -rf docs/_build
tox run -e docs-dev

the warnings:

The HTML pages are in docs/_build/html.
docs-dev: commands[1]> python tests/utils/check_warnings.py

=== Sphinx Warnings test ===

Checking build warnings in file: "/home/kayce/github/kaycebasques/pydata-sphinx-theme/warnings.txt" and comparing to expected warnings defined in "/home/kayce/github/kaycebasques/pydata-sphinx-theme/tests/warning_list.txt" and "/home/kayce/github/kaycebasques/pydata-sphinx-theme/tests/intermittent_warning_list.txt"

Unexpected warning: WARNING: Aborted attempted copy from /home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/_build/html/.doctrees/nbsphinx/examples/pydata.ipynb to /home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/_build/html/examples/pydata.ipynb (the destination path has existing data). [misc.copy_overwrite]

docs-dev: exit 1 (0.35 seconds) /home/kayce/github/kaycebasques/pydata-sphinx-theme> python tests/utils/check_warnings.py pid=143269
.pkg: _exit> python /home/kayce/github/kaycebasques/pydata-sphinx-theme/venv/lib/python3.11/site-packages/pyproject_api/_backend.py True sphinx_theme_builder
  docs-dev: FAIL code 1 (18.28=setup[6.28]+cmd[11.65,0.35] seconds)
  evaluation failed :( (18.49 seconds)

there's also a bunch of images and stubs not found but I guess I can ignore these?

reading sources... [ 99%] user_guide/warnings
reading sources... [100%] user_guide/web-components

/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/arviz.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/bokeh.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/brightway.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/jupyter.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/jupyter_book.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/matplotlib.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/mne-python.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/networkx.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/numpy.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/pandas.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/scipy.png [image.not_readable]
/home/kayce/github/kaycebasques/pydata-sphinx-theme/docs/examples/gallery.md:: WARNING: image file not readable: _static/gallery/sepal.png [image.not_readable]
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.DefragResult:8: WARNING: autosummary: stub file not found 'urllib.parse.DefragResult.count'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.DefragResult:8: WARNING: autosummary: stub file not found 'urllib.parse.DefragResult.index'. Check your autosummary_generate setting.
looking for now-outdated files... none found
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.DefragResultBytes:8: WARNING: autosummary: stub file not found 'urllib.parse.DefragResultBytes.count'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.DefragResultBytes:8: WARNING: autosummary: stub file not found 'urllib.parse.DefragResultBytes.index'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.ParseResult:21: WARNING: autosummary: stub file not found 'urllib.parse.ParseResult.count'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.ParseResult:21: WARNING: autosummary: stub file not found 'urllib.parse.ParseResult.index'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.ParseResultBytes:21: WARNING: autosummary: stub file not found 'urllib.parse.ParseResultBytes.count'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.ParseResultBytes:21: WARNING: autosummary: stub file not found 'urllib.parse.ParseResultBytes.index'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.SplitResult:21: WARNING: autosummary: stub file not found 'urllib.parse.SplitResult.count'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.SplitResult:21: WARNING: autosummary: stub file not found 'urllib.parse.SplitResult.index'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.SplitResultBytes:21: WARNING: autosummary: stub file not found 'urllib.parse.SplitResultBytes.count'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.SplitResultBytes:21: WARNING: autosummary: stub file not found 'urllib.parse.SplitResultBytes.index'. Check your autosummary_generate setting.
/usr/lib/python3.11/urllib/parse.py:docstring of urllib.parse.quote:14: ERROR: Unexpected indentation. [docutils]
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... 
copying downloadable files... [100%] ../src/pydata_sphinx_theme/assets/styles/variables/_color.scss
trallard commented 1 month ago

eHi @kaycebasques, thanks for contributing to PST.

installing pandoc over pip didn't work. had to install system-wide.

In the guide - Install your tools - we add pandoc as a pre-requisite, perhaps should note this should be installed system-wide

ditto. python3 -m pip install graphviz

Same, I think we need to add a note about installing this (it was recently added, so it seems like it was missed)

I need to check the stubs warnings, but they can be safely ignored. However, the documentation could be tweaked overall to better support contributors.

FYI I updated the issue title to reflect the changes needed a bit better