Automate documentation builds with nox

[choldgraf]

Description

I find the developer documentation for this theme to be pretty complex, especially as someone without a lot of background in npm / webpack / yarn workflows. As noted in #468 , I have a lot of weird behavior when I run yarn build:dev and I have no idea how to resolve this. It makes developing this theme really cumbersome for me, and I suspect that other potential developers may have similar issues since many Python devs who come to this theme are not familiar with JS workflows either.

I think it'd be helpful if we provided a one-command method of installing development dependencies, generating asset bundles, and building / previewing the documentation.

I've found that the nox package is a really nice / lightweight way to do things like this. For example, we could turn most of our "Set up a development environment" documentation into two commands:

pip install nox
nox -s docs

Benefits of this approach

I think the main benefits to this are:

1. nox is more python-friendly than manually installing and running yarn
2. nox is more flexible and we could also use it for running our tests
3. nox handles the virtual environment for you, so you're more certain that your dev environment is what you expect.

Implementation details

I think that this could be accomplished with a nox config like this:

@nox.session(venv_backend='conda')
def docs(session):
    session.conda_install("--channel=conda-forge", "yarn")
    session.install("-r", "docs/requirements.txt")
    session.install("-e", ".")

    session.run("yarn", "build")
	session.run("sphinx-build", "docs", "docs/_build/html")

or for docs previews, it might be the following (and invoked with nox -s docs-live:

@nox.session(name="docs-live", venv_backend='conda')
def docs_live(session):
    session.conda_install("--channel=conda-forge", "yarn")
    session.install("-r", "docs/requirements.txt")
    session.install("-e", ".")

    session.run("yarn", "build:dev")

[drammock]

+100. I don't know if nox is the best fix, but a fix is definitely needed. Currently, contributing to the theme requires:

• conda install -c conda-forge --file docs/requirements.txt
• installing nodejs --- specifically version 14 (this is not documented on the contributing page; conda install yarn will pull in version 16, which has lots of version conflicts with other required packages, cf fix dependency installation and build #467)
• editable pip install of the repo clone
• installing and running yarn
• installing and running pre-commit

In addition, I think y'all need to pin some of your yarn dependencies. I literally just did the above steps in a new conda environment, and running yarn yields over 800 changed lines in yarn.lock versus current master. That means every time a new contributor sets up a dev environment in order to contribute, they're going to change the package versions for everyone.

[choldgraf]

As an aside - what do we use webpack for? Is it just for bundling our Javascript and SCSS as assets in the package? If that is the case, I'd also suggest we consider using web-compile, a little pure-python tool that does the same thing without adopting a whole different toolchain.

[jorisvandenbossche]

As an aside - what do we use webpack for? Is it just for bundling our Javascript and SCSS as assets in the package? If that is the case, I'd also suggest we consider using web-compile, a little pure-python tool that does the same thing without adopting a whole different toolchain.

Indeed, it's being used for building the SCSS sources and bundling them. If you have been happily using web-compile with the executable-books projects, it sounds good to switch here as well

[choldgraf]

I've found web-compile to be much simpler and faster than the whole webpack toolchain. I think our problem is that we're using webpack for a lot of other stuff too, like vendoring fontawesome + bootstrap. In my opinion this is hard to maintain and follow since none of us are JS devs. I am curious what you think about just manually bundling all assets with this repository, removing webpack entirely, and then using web-compile to compile our theme-specific CSS and JS