Skip to content

Commit

Permalink
Documentation: Update development sandbox documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@amotl
amotl committed Nov 21, 2022
1 parent 0920548 commit c19b889
Showing 1 changed file with 73 additions and 61 deletions.
134 changes: 73 additions & 61 deletions docs/contribution/development.rst
View file
@@ -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
Expand All @@ -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.

0 comments on commit c19b889

Please sign in to comment.