diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..804d479 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,50 @@ +Contributing +============ + +If you want to improve the code base, add a feature or update the +documentation please open a `pull request`_. Feel free to `open an issue`_ +beforehand to discuss your plans. + +.. _pull request: https://github.com/painless-software/python-cli-test-helpers/pulls +.. _open an issue: https://github.com/painless-software/python-cli-test-helpers/issues + +Development +----------- + +This project uses Tox to run its test suite. Install it using Pip like this: + +.. code-block:: shell + + python3 -m pip install tox + +Alternatively, if you use `uv`_, install Tox as a development tool like this: + +.. code-block:: shell + + uv tool install tox --with tox-uv + +Usage: + +.. code-block:: shell + + tox list # list available environments + tox -e py # run tests with local default Python + tox -e lint,format # run a few environments + tox # run entire suite + +.. _uv: https://docs.astral.sh/uv/ + +Documentation +------------- + +Build the documentation locally and view it in your Web browser: + +.. code-block:: console + + $ tox -e clean,docs + ... + $ cd docs/_build/html/ + $ python -m http.server + Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ... + +Click on the displayed link to inspect the generated documentation. diff --git a/README.rst b/README.rst index fe5f40c..4e015ce 100644 --- a/README.rst +++ b/README.rst @@ -42,6 +42,7 @@ arguments and environment variable values. .. _docopt: http://docopt.org/ .. _documentation: https://python-cli-test-helpers.readthedocs.io/ .. _CLI Copier template: https://gitlab.com/painless-software/cicd/app/cli +.. _CONTRIBUTING: https://github.com/painless-software/python-cli-test-helpers/blob/main/CONTRIBUTING.rst .. links-marker @@ -61,16 +62,4 @@ effortlessly. Development ----------- -This project uses Tox to run its test suite. Install and use it locally like -this: - -.. code-block:: shell - - python3 -m pip install tox - -.. code-block:: shell - - tox list # list available environments - tox -e lint,py312 # run a few environments - tox -e py # run tests with local default Python - tox # run entire suite +See `CONTRIBUTING`_. diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..e582053 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst diff --git a/docs/index.rst b/docs/index.rst index dcd8f45..49fe44c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,7 @@ Contents tutorial other techniques + contributing Quotes ------