sphinx-contrib/sphinx-lint

Improve "Contributing" section in the README

Opened this issue · 2 comments

ezio-melotti commented

I think it would be useful to document:

  • how to set up the venv
  • what dependencies should be installed
  • how/when to download the friends repos
  • how to run the test suite and individual tests
  • how/where to add tests

After creating the venv and trying to run the test suite, I got some errors about missing dependencies and since there is no requirements.txt I had to figure them out until the errors stopped. When I went to add the tests I had to figure out the xpass and xfail dirs and then I got some errors because I didn't add the .. expect: directive. Even though eventually I figured all these things out, other contributors might not, and I could have saved some time if these things were documented.

hugovk commented

Adding tox would be useful here: it can take care of virtualenvs, installing dependencies, running tests, and also make it easy to test on multiple Python versions.

  • 👍1
ezio-melotti commented

For tox, see:

In the meanwhile, these are the commands as a reference.

how to set up the venv
what dependencies should be installed

$ python3 -m venv venv  # create venv
$ source .venv/bin/activate  # activate it
$ pip install -e .  # install `sphinx-lint` and its deps

how/when to download the friends repos

$ # when all regular tests pass and you want more
$ sh download-more-tests.sh  # download more projects to test

how to run the test suite and individual tests

$ pytest -v
$ pytest -v tests/test_sphinxlint.py::test_sphinxlint_shall_pass
$ pytest -v tests/test_sphinxlint.py::test_sphinxlint_shall_pass[...]

how/where to add tests

$ ll tests/fixtures/x
xfail/ xpass/

Valid markup should go in a file in xpass, invalid markup in a file in xfail.
Files in xfail should contain at the beginning one or more

.. expect: N: Error message (checker-name)

You can run

$ sphinx-lint -i venv/ tests/fixtures/xfail/file-name.rst

to get the list of failures.