diff --git a/docs/contribution/development.rst b/docs/contribution/development.rst index 6bbaff3f8..a5717d4d6 100644 --- a/docs/contribution/development.rst +++ b/docs/contribution/development.rst @@ -1,16 +1,26 @@ -Development -########### +################### +Development sandbox +################### -Whether you work on an issue, try to implement a new feature or work on adding a new weather service, you'll need a -proper working environment. The following describes how to setup such an environment and how to enable you to -satisfy our code quality rules which would ultimately fail on Github CI and block a PR. -1. Clone the library and install the environment. +************ +Introduction +************ - This setup procedure will outline how to install the library and the minimum - dependencies required to run the whole test suite. If, for some reason, you - are not available to install all the packages, just leave out some of the - "extras" dependency tags. +Whether you are working on an issue, trying to implement a new feature, or adding +a new weather service, you'll need a proper sandbox environment. The following +procedure outlines how to setup such an environment. + +This setup procedure will outline how to install the library and the minimum +dependencies required to run the whole test suite. + +If, for some reason, you are not available to install all the packages, just +leave out some of the ``extras`` dependency groups. + + +********************************* +Acquire sources and prerequisites +********************************* .. code-block:: bash @@ -19,80 +29,82 @@ satisfy our code quality rules which would ultimately fail on Github CI and bloc # Prerequisites brew install --cask firefox - brew install git python geckodriver + brew install git python geckodriver poetry - # Option 1: Basic - git clone https://github.com/earthobservations/wetterdienst - cd wetterdienst - python3 -m venv .venv - source .venv/bin/activate - pip install --requirement=requirements.txt - python setup.py develop + # Other OS + # You can also get installers and/or release archives for Linux, macOS + # and Windows at + # + # - https://python-poetry.org/docs/#installation + # - https://www.mozilla.org/en-US/firefox/new/ + # - https://github.com/mozilla/geckodriver/releases - # (Option 2: Install package with extras) - pip install ".[sql,export,restapi,explorer,interpolation]" - # Option 3: Install package with extras using poetry. +************ +Using Poetry +************ + +.. code-block:: bash + poetry install --with=test,dev,docs --extras=sql --extras=export --extras=restapi --extras=explorer --extras=interpolation poetry shell -2. For running the whole test suite, you will need to have Firefox and - geckodriver installed on your machine. Install them like:: - # macOS - brew install --cask firefox - brew install geckodriver +********* +Using pip +********* + +.. code-block:: bash + + python3 -m venv .venv + source .venv/bin/activate - # Other OS - # You can also get installers and/or release archives for Linux, macOS - # and Windows at - # - # - https://www.mozilla.org/en-US/firefox/new/ - # - https://github.com/mozilla/geckodriver/releases + # Install package in "editable" mode. + pip install --editable=".[sql,export,restapi,explorer,interpolation]" - If this does not work for some reason and you would like to skip ui-related - tests on your machine, please invoke the test suite with:: + # As a last resort, if all other methods fail. + pip install --requirement=requirements.txt - poe test -m "not ui" -3. Edit the source code, add corresponding tests and documentation for your - changes. While editing, you might want to continuously run the test suite - by invoking:: +********* +Run tests +********* - poe test +For running the whole test suite, you will need to have Firefox and +geckodriver installed on your machine:: - In order to run only specific tests, invoke:: + poe test - # Run tests by module name or function name. - poe test -k test_cli +If this does not work for some reason and you would like to skip ui-related +tests on your machine, please invoke the test suite with:: - # Run tests by tags. - poe test -m "not (remote or slow)" + poe test -m "not ui" -4. Before committing your changes, please als run those steps in order to make - the patch adhere to the coding standards used here. +In order to run only specific tests, invoke:: -.. code-block:: bash + # Run tests by module name or function name. + poe test -k test_cli - poe format # black code formatting - poe lint # lint checking - poe export # export of requirements (for Github Dependency Graph) + # Run tests by tags. + poe test -m "not (remote or slow)" -5. Push your changes and submit them as pull request - That's it, you're almost done! We'd already like to thank you for your commitment! +************ +Contributing +************ -6. Wait for our feedback. We'll probably come back to you in a few days and let you know if there's anything that may - need some more polishing. +1. Before committing your changes, please als run those steps in order to make + the patch adhere to the coding standards used here. -.. note:: + .. code-block:: bash - If you need to extend the list of package dependencies, invoke: + poe format # black code formatting + poe lint # lint checking + poe export # export of requirements (for Github Dependency Graph) - .. code-block:: bash +2. Push your changes and submit them as pull request. - # Add package to runtime dependencies. - poetry add new-package + That's it, you're almost done! We'd already like to thank you for taking the time to contribute. - # Add package to development dependencies. - poetry add --dev new-package +3. Wait for our feedback. We'll probably come back to you in a few days and let you know + if there's anything that may need some more polishing.