diff --git a/CHANGES.rst b/CHANGES.rst index 00ad5176..3eb3b2cb 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -17,7 +17,9 @@ Breaking changes: New features: -- *add item here* +- Document development setup + Ref: #358 + [niccokunzmann] Bug fixes: diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 66e28eb9..37e0bc63 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -21,3 +21,11 @@ For pull requests, keep this in mind - Describe your change in CHANGES.rst - Add yourself to the docs/credits.rst + +Development Setup +----------------- + +If you would like to setup icalendar to +contribute changes, the `Installation Section +`_ +should help you further. diff --git a/docs/credits.rst b/docs/credits.rst index 420af8d4..3086e6e9 100644 --- a/docs/credits.rst +++ b/docs/credits.rst @@ -56,6 +56,7 @@ icalendar contributors - Clive Stevens - Dalton Durst - Kamil MaƄkowski +- `Nicco Kunzmann `_ Find out who contributed:: diff --git a/docs/install.rst b/docs/install.rst index 8556b05e..8c8b1c7a 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -10,6 +10,109 @@ package, like this:: >>> import icalendar +Development Setup +----------------- + +To start contributing changes to icalendar, +you can clone the project to your file system +using Git. +You can `fork `_ +the project first and clone your fork, too. + +.. code-block:: bash + + git clone https://github.com/collective/icalendar.git + cd icalendar + +Installing Python +----------------- + +You will need a version of Python installed to run the tests +and execute the code. +The latest version of Python 3 should work and will be enough +to get you started. +If you like to run the tests with different Python versions, +the following setup proecess should work the same. + +Install Tox +----------- + +First, install `tox `_.. + +.. code-block:: bash + + pip install tox + +From now on, tox will manage Python versions and +test commands for you. + +Running Tests +------------- + +``tox`` manages all test environments in all Python versions. + +To run all tests in all environments, simply run ``tox`` + +.. code-block:: bash + + tox + +You may not have all Python versions installed or +you may want to run a specific one. +Have a look at the `documentation +`__. +This is how you can run ``tox`` with Python 3.9: + +.. code-block:: bash + + tox -e py39 + +Accessing a ``tox`` environment +------------------------------- + +If you like to enter a specific tox environment, +you can do this: + +.. code-block:: bash + + source .tox/py39/bin/activate + +Install ``icalendar`` Manually +------------------------------- + +The best way to test the package is to use ``tox`` as +described above. +If for some reason you cannot install ``tox``, you can +go ahead with the following section using your +installed version of Python and ``pip``. + +If for example, you would like to use your local copy of +icalendar in another Python environment, +this section explains how to do it. + +You can install the local copy of ``icalendar`` with ``pip`` +like this: + +.. code-block:: bash + + cd icalendar + python -m pip install -e . + +This installs the module and dependencies in your +Python environment so that you can access local changes. +If tox fails to install ``icalendar`` during its first run, +you can activate the environment in the ``.tox`` folder and +manually setup ``icalendar`` like this. + +Try it out: + +.. code-block:: python + + Python 3.9.5 (default, Nov 23 2021, 15:27:38) + Type "help", "copyright", "credits" or "license" for more information. + >>> import icalendar + >>> icalendar.__version__ + '4.0.10.dev0' Building the documentation locally ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -18,10 +121,7 @@ To build the documentation follow these steps: .. code-block:: bash - $ git clone https://github.com/collective/icalendar.git - $ cd icalendar - $ virtualenv-2.7 . - $ source bin/activate + $ source .tox/py39/bin/activate $ pip install -r requirements_docs.txt $ cd docs $ make html diff --git a/tox.ini b/tox.ini index 5ca22932..688d2c5f 100644 --- a/tox.ini +++ b/tox.ini @@ -1,16 +1,15 @@ # to run for a specific environment, use ``tox -e ENVNAME`` [tox] -envlist = py27,py36,py37,py38,py39,py310,pypy3 +envlist = py27,py37,py38,py39,py310,pypy3 [testenv] +usedevelop=True deps = pytest coverage - py{27,36}: hypothesis>=3.0 -extras = - test + py{27}: hypothesis>=3.0 commands = coverage run --source=src/icalendar --omit=*/tests/* --module pytest [] - py{27,36}: coverage run --append --source=src/icalendar --omit=*/tests/* --module pytest [] src/icalendar/tests/hypothesis/ + py{27}: coverage run --append --source=src/icalendar --omit=*/tests/* --module pytest [] src/icalendar/tests/hypothesis/ coverage report coverage html