👌 IMPROVE: Nicer Development Experience

[pradyunsg]

Closes #151 in my opinion. :)

Following @choldgraf's nudge, I ended up writing the entire noxfile for this project and rewrote a part of the contributing guide to reflect what the various commands needed during development look like with nox.

Oh, and I added the nox -s docs-live thing, with live-reload through sphinx-autobuild as well. :)

[pradyunsg]

Oh. Oh. CI improvements!

[chrisjsewell]

Heya I'll have a proper look later ta. But I note from a first glance that you haven't altered the pre-commit, to ensure the css is up to date with the sass. IMO This is also the way the project should be linted, not via nox

[chrisjsewell]

The live compiling is good though 👍

[chrisjsewell]

You might also want to add: https://github.com/pre-commit/mirrors-scss-lint

[pradyunsg]

I note from a first glance that you haven't altered the pre-commit, to ensure the css is up to date with the sass.

I don't see why that would be necessary -- I've not re-added the compiled file into version control. It is still generated by compiling the SCSS file. The difference is that it's not compiled as part of the sphinx-build run, but separately (through boussole watch/compile).

IMO This is also the way the project should be linted, not via nox

nox is not a linter, but being used to run the linters (nox -s lint installs and runs pre-commit).

[chrisjsewell]

The other question that came to mind is using this in a conda environment, where I do all my development. There's some notes on this here: https://nox.thea.codes/en/stable/tutorial.html#testing-with-conda

[pradyunsg]

The other question that came to mind is using this in a conda environment

Hmm... I don't think using conda is necessary here. All the packages in our dependency tree have wheels on all major platforms and the specific case of testing this theme doesn't need any performance optimized variants of those packages IMO.

[pradyunsg]

You might also want to add: pre-commit/mirrors-scss-lint

I'd prefer we do this separately, because I already feel like I'm changing a lot of things in this one. :)

[pradyunsg]

I don't think using conda is necessary here.

To be clear, this will still work in a conda environment that has a Python in it. It'll create the isolated environments for each of the sessions using the conda environment's Python, in a .nox directory and the exact same commands will do the right thing.

[chrisjsewell]

I've not re-added the compiled file into version control

Yes but I think they should be in the version control, otherwise people can only use the package directly when installing from pypi (because you run the compile in the publish workflow), and for example the RTD PR builds are now broken: https://sphinx-book-theme--172.org.readthedocs.build/en/172/

[pradyunsg]

people can only use the package directly when installing from pypi (because you run the compile in the publish workflow)

That's something I didn't realize. :)

for example the RTD PR builds are now broken

Oooooo.

[pradyunsg]

That should do it. :)

[pradyunsg]

Okay, this should be good to go. realizes he didn't mark this PR as a draft earlier Oh nvm. 😅

[chrisjsewell]

nearly there! I'll also just have a play around with using it locally before merging

[pradyunsg]

Note to self: don't dev on pre-commit while also working on other projects. It can result in bad things happening.

[chrisjsewell]

Unless I'm missing something; with live-build, if you update the scss, it will compile the css in docs/_static, but sphinx won't pick up on this and so it doesn't get re-copied to docs/_build/html and thus update in the browser.
I think this was mentioned before, but is there any way we can rectify this: via sphinx or just separately adding a copy command to nox?

[chrisjsewell]

This is brought up in sphinx-doc/sphinx-autobuild#34, but as also previously discussed, sphinx-autobuild is an "abandoned" package which is not ideal, although if/while it works thats not necessarily a problem for a dev dependency

[chrisjsewell]

This is also the upstream issue: sphinx-doc/sphinx#2090

[pradyunsg]

Looks like changing conf.py is an option, based on sphinx issue's last comment.

[pradyunsg]

All done! Ready to go!

[pradyunsg]

Closed-reopened to retrigger CI for the failed codecov upload.

[chrisjsewell]

🎉 🥳

[choldgraf]

A few comments from me - I guess @chrisjsewell already merged but it'd be great to hear @pradyunsg 's responses nonetheless!

[choldgraf]

how does this work with arguments passed to pytest? E.g. I often do pytest -k aspecifictest or pytest -s so that I can start an IPython kernel from within the test.

[chrisjsewell]

nox just calls pytest within a particular virtualenv (which it builds) that gets created in a folder in the repository folder. But you can still run pytest normally if you don't want to use nox

[pradyunsg]

I was wondering if I should mention it here. The form is nox -s tests-3.8 -- (pytest-args).

[pradyunsg]

Do we want to document this? If so, please file an issue referencing the above comment.

[pradyunsg]

Happy to respond. :)

Dinner time right now - ill try to resolve those concerns before sleeping today.