Improve developer workflow and docs

[choldgraf]

This PR tries to address some of the major pain points of setting up a development workflow with this theme.

It does a few major things:

1. Overhauls our developer documentation to be easier to follow and quickly jump between sections.
2. It also tries to add more explicit steps install various things and invoke them properly
3. Adds a noxfile.py so that developers can use nox if they wish
4. Adds instructions about nox as an "automatic setup" step in the dev docs
5. Updates some of our setup.py dependencies to include developer tooling, and references these in our dev docs.

I would love to hear from @drammock in particular whether these instructions would have reduced the setup time for working on the theme.

closes #487

new developer docs are here: https://pydata-sphinx-theme--490.org.readthedocs.build/en/490/contributing.html

[drammock]

The initial dev setup / installation is much easier now! However I do have a couple critiques:

1. nox is creating a new conda env every time you build the static docs, or spin up the live locally-served docs. That slows things down quite a bit, though in the big picture maybe worth it?
2. Found the problem, see code review suggestion. nox -s docs-live runs the tests instead of spinning up a local server? After creating a fresh conda env with only python/pip in it, I ran pip install .[dev] and pre-commit install and then nox -s docs-live and this is what I got:

$ nox -s docs-live
nox > Running session docs-live
nox > Creating conda env in .nox/docs-live with python
nox > conda install --yes --prefix /opt/pydata-sphinx-theme/.nox/docs-live --channel conda-forge yarn "nodejs>=14,<15" pip
nox > python -m pip install -r docs/requirements.txt
nox > python -m pip install -e .
nox > pytest 
==================================================================================================================================================== test session starts =====================================================================================================================================================
platform linux -- Python 3.9.7, pytest-6.2.5, py-1.10.0, pluggy-1.0.0
rootdir: /opt/pydata-sphinx-theme
plugins: datadir-1.3.1, regressions-2.2.0
collected 31 items                                                                                                                                                                                                                                                                                                           

tests/test_build.py ...............................                                                                                                                                                                                                                                                                    [100%]

===================================================================================================================================================== 31 passed in 5.53s =====================================================================================================================================================
nox > Session docs-live was successful.

At that point I had a waiting shell prompt so I assumed no server was running, but I double-checked localhost:1919 just to be sure --- unable to connect.

3. nox -s docs-live terminal output provides a link to localhost:8000; the correct location is localhost:1919

[choldgraf]

Thanks for these comments! I've merged the suggestion you made - good catch!

For re-using environments, I think it does reuse them, so it calls the commands to install, but the environments should already be there. That said, conda does tend to take a little while to figure this out anyway. So I just pushed an update that checks whether sphinx exists in the venv, and if it does, it skips the install steps entirely.

This means that if you want to re-build the environment you'll have to manually delete it, but I think that's a reasonable trade-off.

[choldgraf]

I'm gonna merge this soon unless there are objections, so that I can continue iterating on the theme a bit, I wanna see if we can quickly improve the slowness stuff

[jorisvandenbossche]

Thanks for working on this, Chris!

I was trying out the new instructions, but I run into a strange issue. It creates a new conda env, but doesn't actually install anything in it.

After having installed nox, I run:

$ nox -s docs -vv
nox > Running session docs
nox > Creating conda env in .nox/docs with python
Collecting package metadata (current_repodata.json): ...working... done
Solving environment: ...working... done

## Package Plan ##

  environment location: /home/joris/scipy/repos/pydata-sphinx-theme/.nox/docs

  added / updated specs:
    - pip
    - python


The following NEW packages will be INSTALLED:

  _libgcc_mutex      conda-forge/linux-64::_libgcc_mutex-0.1-conda_forge
  _openmp_mutex      conda-forge/linux-64::_openmp_mutex-4.5-1_gnu
  ca-certificates    conda-forge/linux-64::ca-certificates-2021.5.30-ha878542_0
  ld_impl_linux-64   conda-forge/linux-64::ld_impl_linux-64-2.36.1-hea4e1c9_2
  libffi             conda-forge/linux-64::libffi-3.4.2-h9c3ff4c_4
  libgcc-ng          conda-forge/linux-64::libgcc-ng-11.2.0-h1d223b6_9
  libgomp            conda-forge/linux-64::libgomp-11.2.0-h1d223b6_9
  libstdcxx-ng       conda-forge/linux-64::libstdcxx-ng-11.2.0-he4da1e4_9
  libzlib            conda-forge/linux-64::libzlib-1.2.11-h36c2ea0_1013
  ncurses            conda-forge/linux-64::ncurses-6.2-h58526e2_4
  openssl            conda-forge/linux-64::openssl-3.0.0-h7f98852_1
  pip                conda-forge/noarch::pip-21.2.4-pyhd8ed1ab_0
  python             conda-forge/linux-64::python-3.9.7-hf930737_3_cpython
  python_abi         conda-forge/linux-64::python_abi-3.9-2_cp39
  readline           conda-forge/linux-64::readline-8.1-h46c0cb4_0
  setuptools         conda-forge/linux-64::setuptools-58.2.0-py39hf3d152e_0
  sqlite             conda-forge/linux-64::sqlite-3.36.0-h9cd32fc_2
  tk                 conda-forge/linux-64::tk-8.6.11-h27826a3_1
  tzdata             conda-forge/noarch::tzdata-2021c-he74cb21_0
  wheel              conda-forge/noarch::wheel-0.37.0-pyhd8ed1ab_1
  xz                 conda-forge/linux-64::xz-5.2.5-h516909a_1
  zlib               conda-forge/linux-64::zlib-1.2.11-h36c2ea0_1013


Preparing transaction: ...working... done
Verifying transaction: ...working... done
Executing transaction: ...working... done


==> WARNING: A newer version of conda exists. <==
  current version: 4.10.2
  latest version: 4.10.3

Please update conda by running

    $ conda update -n base conda


#
# To activate this environment, use
#
#     $ conda activate /home/joris/scipy/repos/pydata-sphinx-theme/.nox/docs
#
# To deactivate an active environment, use
#
#     $ conda deactivate


nox > cd docs
nox > make html
nox > Warning: make is not installed into the virtualenv, it is located at /usr/bin/make. This might cause issues! Pass external=True into run() to silence this message.
/bin/sh: 1: sphinx-build: not found
make: *** [Makefile:20: html] Error 127
nox > Command make html failed with exit code 2
nox > Session docs failed.

So it only created the conda env, but didn't install anything in it, and thus the doc build of course fails. I don't directly see anything in the verbose output. Any idea where to look ?

[jorisvandenbossche]

OK, so with -- reinstall it actually does the right thing, but so the check you added for sphinx already being present fails for me: the bin.rglob("sphinx-build") seems to return a generator which evaluates to True in a boolean context (the if check), while it's actually empty (list(bin.rglob("sphinx-build")) == []).
(that should be an easy fix, will look further tomorrow)

[choldgraf]

ahhh gotcha - we should definitely fix this! (sorry for the fast merge, I wanted to get it in before I could do some other dev here)

[jorisvandenbossche]

Some other questions / comments:

• Is it needed to have nox use different environments for building the docs (docs) and building the scss sources (build) and the other sessions? That seems a bit of a wast, since they are identical environments (and you actually need to build the sources first to correctly build the docs).
  Checking, this seems not yet possible (Add ability for many nox tasks to reuse the same session/virtual env wntrblm/nox#167)
• For my own personal workflow, I would prefer to just use the existing environment from where I am calling nox (which actually also gives the "single dev environment" from the point above). It seems this is possible by forcing the backend to be none (https://nox.thea.codes/en/stable/usage.html#forcing-the-sessions-backend). That makes that you can use the short-cuts from nox, while having more control over the environment (eg I regularly checkout a specific version of sphinx while developing on this theme, or set a breakpoint, ..)

[choldgraf]

I gave a shot at documenting this in #495 !