getting-started.rst (2233B)
1 Getting started 2 =============== 3 4 Working on packaging requires the installation of a small number of 5 development dependencies. To see what dependencies are required to 6 run the tests manually, please look at the ``noxfile.py`` file. 7 8 Running tests 9 ~~~~~~~~~~~~~ 10 11 The packaging unit tests are found in the ``tests/`` directory and are 12 designed to be run using `pytest`_. `pytest`_ will discover the tests 13 automatically, so all you have to do is: 14 15 .. code-block:: console 16 17 $ python -m pytest 18 ... 19 29204 passed, 4 skipped, 1 xfailed in 83.98 seconds 20 21 This runs the tests with the default Python interpreter. This also allows 22 you to run select tests instead of the entire test suite. 23 24 You can also verify that the tests pass on other supported Python interpreters. 25 For this we use `nox`_, which will automatically create a `virtualenv`_ for 26 each supported Python version and run the tests. For example: 27 28 .. code-block:: console 29 30 $ nox -s tests 31 ... 32 nox > Ran multiple sessions: 33 nox > * tests-3.6: success 34 nox > * tests-3.7: success 35 nox > * tests-3.8: success 36 nox > * tests-3.9: success 37 nox > * tests-pypy3: skipped 38 39 You may not have all the required Python versions installed, in which case you 40 will see one or more ``InterpreterNotFound`` errors. 41 42 Running linters 43 ~~~~~~~~~~~~~~~ 44 45 If you wish to run the linting rules, you may use `pre-commit`_ or run 46 ``nox -s lint``. 47 48 .. code-block:: console 49 50 $ nox -s lint 51 ... 52 nox > Session lint was successful. 53 54 Building documentation 55 ~~~~~~~~~~~~~~~~~~~~~~ 56 57 packaging documentation is stored in the ``docs/`` directory. It is 58 written in `reStructured Text`_ and rendered using `Sphinx`_. 59 60 Use `nox`_ to build the documentation. For example: 61 62 .. code-block:: console 63 64 $ nox -s docs 65 ... 66 nox > Session docs was successful. 67 68 The HTML documentation index can now be found at 69 ``docs/_build/html/index.html``. 70 71 .. _`pytest`: https://pypi.org/project/pytest/ 72 .. _`nox`: https://pypi.org/project/nox/ 73 .. _`virtualenv`: https://pypi.org/project/virtualenv/ 74 .. _`pip`: https://pypi.org/project/pip/ 75 .. _`sphinx`: https://pypi.org/project/Sphinx/ 76 .. _`reStructured Text`: http://sphinx-doc.org/rest.html 77 .. _`pre-commit`: https://pre-commit.com