Add nox config to automate building docs

[gotmax23]

It would be nice to have a nox or tox configuration to clone ansible-core, install the necessary build dependencies in a managed virtualenv, and build docs. This improves the contributor experience, as they can run one command instead of four (clone core, create venv, install deps, run Makefile) to build the docs.

nox and tox both preform similar purposes. They allow running different jobs and manage each job's dependencies in a separate virtualenv. nox has its config in Python and tox has a domain-specific INI-like configuration format. I personally prefer nox, and we successfully adopted it in the 5 antsibull projects, but other projects in the ecosystem use tox.

/cc @mattclay

[gotmax23]

I have have a simple noxfile locally that just sets up a venv and calls make:

from __future__ import annotations

import nox


@nox.session
def make(session: nox.Session) -> None:
    session.install("-r", "docs/docsite/requirements.txt")
    session.run("make", "-C", "docs/docsite/", *session.posargs, external=True)

I'm not sure that this is the best solution (we might want to create separate nox sessions to correspond to Makefile targets or move things out of the Makefile), but nox -- coredocs works for me for now.

[webknjaz]

Since you asked for feedback, I'll say that using nox is probably a better fit for a docs project, even though I tend to use tox myself. Hynek recently mentioned that nox doesn't do parallelism well (https://hynek.me/articles/turbo-charge-tox/) but it's probably unnecessary here. I'll let @oraNod make that decision.

[oraNod]

+1 to nox. I'm sure there are other pros and cons to consider but my preference is for Python over ini. I feel like there would be some advantages there when/if we do move things out of the Makefile.

[webknjaz]

when/if we do move things out of the Makefile.

I'd argue that it's supposed to replace makefile and removing it should be a part of the PR that integrates nox. If noxfile is added but not integrated, it won't be tested and much less people may end up using it.

[felixfontein]

I would probably leave a Makefile that translates the existing Makefile targets to nox commands (at least for a while). That way folks can still use their make xxx commands (and see to which nox -e ... commands these translate).

[gotmax23]

Are we defining the scope of this as

1. completely replacing the current Makefile with nox and re-implementing the whole thing in nox's Python syntax

or

2. just adding a noxfile that calls the existing Makefile targets and has extra sessions to generate constraints with pip-compile (Updating doc build requirements #108) and run linters and such

?

[webknjaz]

Please, don't call make from nox. That defeats the entire purpose of it being the main workflow too.l.

[samccann]

I'm +1 for simplifying the docs build. I forget the core clone..ahem... regularly. I don't know enough about make vs nox/tox to have an opinion.

[samccann]

As part of this change, is it possible to move the ability to make docs (whatever the new command is) into the root dir instead of having to cd to docs/docsite every time? Historically it was this way only because we were part of ansible/ansible and had separate makes from their project make so to speak.

..I'm lazy and tired of the extra step :-)

[gotmax23]

@samccann, yes that's the plan. You can currently run make -C docs/docsite as one command, but that's still not so nice.

[oraNod]

Thanks for all the work here @gotmax23 I think we can close this out now that we have nox sessions for all ci tooling as well as make. We can create follow on issues as needed to capture the work of porting make syntax to nox. As I mentioned elsewhere I hope nox tooling will also allow us to tackle break the package docs build into separate stages. It might be wishful thinking on my part but I think that approach combined with some Sphinx optimizations is the way forward.