Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: Fix dev env instructions in contributors' guide, and explain nox usage in other areas, e.g. tests #591

Closed
ItamarFruchter opened this issue Nov 16, 2022 · 1 comment · Fixed by #592
Assignees
Labels
BUG Something isn't working DOC: documentation documentation
Projects

Comments

@ItamarFruchter
Copy link

The 'Contributors Guide' section on the VAK documents is outdated, specifically working with the makefile.

@ItamarFruchter ItamarFruchter added the BUG Something isn't working label Nov 16, 2022
@NickleDave NickleDave self-assigned this Nov 16, 2022
@NickleDave NickleDave changed the title BUG: Outdated documentation (Contributors guide) DOC: Fix dev env instructions in contributors' guide, and explain nox usage in other areas, e.g. tests Nov 16, 2022
@NickleDave NickleDave added the DOC: documentation documentation label Nov 16, 2022
@NickleDave
Copy link
Collaborator

Thank you @ItamarFruchter for catching this and sorry again for the inconvenience

We need to do two things here:

  • fix that sections of "setting up a dev environment" to explain nox usage
  • also explain nox usage in other parts of that page, e.g. how to run tests + build docs

The "setting up a dev environment" should be updated like so

as a developer

This project uses the library nox
as a task runner,
to automate tasks like setting up a development environment.
Each task is represented as what nox calls a "session",
and you can run a session by invoking nox
at the command-line with the name of the session.

So, to set up a virtual environment for development
with songdkl installed in "editable" mode,
run the "dev" session.

(copying from 'songdkl` README: https://raw.githubusercontent.com/NickleDave/songdkl/main/README.md)

We suggest using pipx
to install nox in an isolated environment,
so that nox can be accessed system-wide without affecting
anything else on your machine.

  1. Install pipx, e.g. with brew
    (and brew works on Linux too)
  2. Install nox with pipx: pipx install nox
  3. Use nox to run the dev session: nox -s dev
  4. Activate the virtual environment: . ./.venv/bin/activate (and/or tell your IDE to use it)

@NickleDave NickleDave added this to To do in DOC Nov 19, 2022
@NickleDave NickleDave moved this from To do to In progress in DOC Nov 19, 2022
NickleDave added a commit that referenced this issue Nov 19, 2022
In contributors.rst.
Also use 'sphinx.ext.autosectionlabel' in doc/conf.py
NickleDave added a commit that referenced this issue Nov 19, 2022
DOC: Fix instructions to set up dev env, fixes #591
@NickleDave NickleDave moved this from In progress to Done in DOC Nov 19, 2022
@NickleDave NickleDave moved this from Done to To do in DOC Jan 22, 2023
@NickleDave NickleDave moved this from To do to In progress in DOC Feb 24, 2023
@NickleDave NickleDave moved this from In progress to Done in DOC Feb 24, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
BUG Something isn't working DOC: documentation documentation
Projects
DOC
Done
Development

Successfully merging a pull request may close this issue.

2 participants