Initial pass at the cookbook

[FollowTheProcess]

Closes #471

This is my initial scaffold for the "cookbook" talked about in the linked issue. I added two of my more "interesting" nox sessions I use regularly to kind of kick it off.

Happy to go any way with this really. If we want it in the docs that's cool, or maybe break out into something separate. Just kicking off a potential idea.

Let me know if we want any changes.

Thanks 👍🏻

[DiddiLeija]

I love the idea @FollowTheProcess! I would like to keep this on the docs, but maybe we should ask another maintainer, like @theacodes.

[henryiii]

This looks really nice! Here are a couple of simpler recipes I use a lot. Maybe recipes could be collection in GitHub Discussions Show & Tell, then the best added?

# Sphinx
@nox.session(reuse_venv=True)
def docs(session):
    """
    Build the docs. Pass "serve" to serve.
    """

    session.install("-e", ".[docs]")
    session.chdir('docs')

    if "pdf" in session.posargs:
        session.run("sphinx-build", "-M", "latexpdf", ".", "_build")
        return

    session.run("sphinx-build", "-M", "html", ".", "_build")

    if "serve" in session.posargs:
        session.log("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")
        session.run("python", "-m", "http.server", "8000", "-d", "_build/html")
    elif session.posargs:
        session.error("Unsupported argument to docs")
            
# MkDocs
@nox.session(reuse_venv=True)
def docs(session: nox.Session) -> None:
    """
    Build the docs.
    """
    session.install("-e", ".[docs]")

    if session.posargs:
        if "serve" in session.posargs:
            session.run("mkdocs", "serve")
        else:
            session.error("Unrecognized args, use 'serve'")
    else:
        session.run("mkdocs", "build")

@nox.session(reuse_venv=True)
def lint(session):
    """
    Run the linter.
    """
    session.install('pre-commit')
    session.run('pre-commit', 'run', '--all-files', *session.posargs)

@nox.session(reuse_venv=True)
def build(session):
    """
    Build an SDist and wheel.
    """

    session.install('build')
    session.run('python', '-m', 'build', *session.posargs)

[DiddiLeija]

@FollowTheProcess, can you please update this branch, so we can go ahead with the PR?

[DiddiLeija]

I'll wait a little before merging, to see if someone has concerns about this :)

[FollowTheProcess]

I'm gonna go ahead and merge this in once the branch has updated, it's been hanging around for a while 🙂