Use nox to manage development

[leouieda]

Nox is a tool that automates setting up virtual environments and running tasks inside them. It's a combination of make and virtual environments. Replace the machinery in our Makefile (which wouldn't work on Windows) with a cross-platform noxfile.py. Since nox handles the virtual environments, the environment.yml only needs to have python and nox. Plus, the environment creation code in the CI is no necessary anymore and we can run tests on multiple python versions locally as well.

Reminders:

• [ ] Run make format and make check to make sure the code follows the style guide.
• [ ] Add tests for new features or tests that would have caught the bug that you're fixing.
• [ ] Add new public functions/methods/classes to doc/api/index.rst and the base __init__.py file for the package.
• [ ] Write detailed docstrings for all functions/classes/methods. It often helps to design better code if you write the docstrings first.
• [ ] If adding new functionality, add an example to the docstring, gallery, and/or tutorials.
• [ ] Add your full name, affiliation, and ORCID (optional) to the AUTHORS.md file (if you haven't already) in case you'd like to be listed as an author on the Zenodo archive of the next release.

[leouieda]

I'm keeping the Makefile so that most instructions on the CONTRIBUTING.md still work but it's just a wrapper of the nox commands. We could remove it entirely and run nox instead.

[leouieda]

Now that I think about it, I would probably organize the CI workflows differently:

• style.yml: stay the same
• test.yml: just have jobs for running the tests and submitting coverage. No docs builds here.
• docs.yml: build the docs and if on master or a release, deploy to gh-pages.
• pypi.yml: deploy to PyPI and TestPyPI.

This way we avoid having multiple duplicate builds of the docs. We could still build on all systems but I think it would be fine to only run it on ubuntu.

[santisoler]

This looks great @leouieda! It's awesome to be capable of running tests on multiple Python versions locally without too much hassle.

For some reason my computer is skipping the py3.6 test:

nox > Session test-3.6 skipped: Python interpreter 3.6 not found.

Do you know why?

I did notice that even if you set up your conda environment, if you try to run nox without internet connection it fails because cannot install the dependencies. Is there a way to preinstall everything that nox needs beforehand so we don't depend on an internet connection for running the tests?

[santisoler]

I did notice that even if you set up your conda environment, if you try to run nox without internet connection it fails because cannot install the dependencies. Is there a way to preinstall everything that nox needs beforehand so we don't depend on an internet connection for running the tests?

Actually there is:

nox --install-only

https://nox.thea.codes/en/stable/usage.html?highlight=offline#skipping-everything-but-install-commands

Buuuut be very careful. If you run nox without the -r option you will undone the previous step and end up with no preinstalled environments. If we remove the Makefile in the future I can certainly see myself breaking my preinstalled environments very often, which will be a pain if I'm a on a place with bad internet connection, or no connection at all.

Maybe we can open an Issue on their repository for this.

[leouieda]

About running offline:

• The --install-only lets you build the environments only without running tests.
• I'm hacking on this in Erizo and will copy over some improvements to allow skipping install steps so that you can work offline

The default is making fresh environments but we can reverse that by setting nox.options.reuse_existing_virtualenvs=True. We can always disable on the command line with --no-reuse-existing-virtualenvs. I'll set this on and then we can skip the -r without much fear of nuking the environments.

[leouieda]

Alright, with the new file after 08e23c4 you can now:

• Reuse environments by default
• Pass in the skip-install option to any session to skip the install step
• Run all checks or selected checks by passing arguments to the check session.

Need to add these instructions to the docstring still.

[leouieda]

@santisoler if you could give this a try locally that would be very helpful. See if you like it and if there are any other pain points we can try to resolve

[leouieda]

@santisoler I made a few changes:

• Added instructions to the noxfile.py docstring
• Added a show option to the docs build that opens the HTML in a web browser. I opted for this instead of serving since it would block the process and the noxfile would just hang. This works just as well and is easily cross-platform using import webbrowser.
• Added rules to the Makefile for nox-clean and nox-install. The update command is not needed since it would be a clean and install anyway.

What do you think?

[santisoler]

This is looking great!

* Added instructions to the noxfile.py docstring

I like that we can list all the available targets with nox -l. We definitely should add this to the Contributing instructions once we ditch the make instructions.

* Added a `show` option to the docs build that opens the HTML in a web browser. I opted for this instead of serving since it would block the process and the noxfile would just hang. This works just as well and is easily cross-platform using `import webbrowser`.

Much better than before!

* Added rules to the Makefile for `nox-clean` and `nox-install`. The update command is not needed since it would be a clean and install anyway.

Sure, I was thinking to add the nox-update target calling the nox-clean and then nox-install, but we don't actually need another target to do so, we can use make nox-clean nox-update on a single line.

I think this is ready to go! Nice work @leouieda !

[leouieda]

Thanks @santisoler! Merging this in. I'll work on a follow up to organize the CIs a bit. Only thing I changed is that setuptools_scm doesn't need to be a run time dependency.