diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 44db7e11..befcee10 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,69 +1,73 @@ - - +============== Contributing -============ +============== + +.. This file based on https://github.com/PyGithub/PyGithub/blob/master/CONTRIBUTING.md + +``map-machine`` uses `tox `_ to automate testing and packaging, +and `pre-commit `_ to maintain code quality. + +Install ``pre-commit`` with ``pip`` and install the git hook: + +.. code-block:: bash + + $ python -m pip install pre-commit + $ pre-commit install + + +Coding style +-------------- + +`formate `_ is used for code formatting. -Thank you for your interest in the Map Machine project. Since the primary goal of the project is to cover as many tags as possible, the project is crucially depend on contributions as OpenStreetMap itself. +It can be run manually via ``pre-commit``: -Modify the code ---------------- +.. code-block:: bash -❗ **IMPORTANT** ❗ Before committing please enable Git hooks: + $ pre-commit run formate -a -```shell -git config --local core.hooksPath data/githooks -``` -This will allow you to automatically check your commit message and code before committing and pushing changes. This will crucially speed up pull request merging and make Git history neat and uniform. +Or, to run the complete autoformatting suite: -### First configure your workspace ### +.. code-block:: bash -Make sure you have Python 3.9 development tools. E.g., for Ubuntu, run `apt install python3.9-dev python3.9-venv`. + $ pre-commit run -a -Activate virtual environment. E.g. for fish shell, run `source venv/bin/activate.fish`. -Install the project in editable mode: +Automated tests +------------------- -```shell -pip install -e . -``` +Tests are run with ``tox`` and ``pytest``. +To run tests for a specific Python version, such as Python 3.10: -Install formatter, linter and test system: `pip install black flake8 mypy pytest pytest-cov`. +.. code-block:: bash -If you are using PyCharm, you may want to set up user dictionary as well: + $ tox -e py310 - * `cp data/dictionary.xml .idea/dictionaries/.xml` - * in `.idea/dictionaries/.xml` change `%USERNAME%` to your username, - * restart PyCharm if it is launched. +To run tests for all Python versions, simply run: -### Code style ### +.. code-block:: bash -We use [Black](http://github.com/psf/black) code formatter with maximum 80 characters line length for all Python files within the project. Reformat a file is as simple as `black -l 80 `. Reformat everything with `black -l 80 map_machine tests`. + $ tox -If you create new Python file, make sure you add `__author__ = " "` and `__email__ = ""` string variables. -### Commit message format ### +Type Annotations +------------------- -The project uses commit messages that starts with a verb in infinitive form with first letter in uppercase, ends with a dot, and is not longer than 50 characters. E.g. `Add new icon.` or `Fix labels.` +Type annotations are checked using ``mypy``. Run ``mypy`` using ``tox``: -If some issues or pull requests are referenced, commit message should starts with prefix such as `PR #123: `, `Issue #42: `, or `Fix #13: ` with the next letter in lowercase. E.g. `PR #123: refactor elements.` or `Issue #42: add icon for natural=tree.` +.. code-block:: bash -Suggest a tag to support ------------------------- + $ tox -e mypy -Please, create an issue describing how you would like the feature to be visualized. -Report a bug ------------- -Please, create an issue describing the current behavior, expected behavior, and environment (most importantly, the OS version and Python version if it was not the recommended one). +Build documentation locally +------------------------------ -Fix a typo in documentation ---------------------------- +The documentation is powered by Sphinx. A local copy of the documentation can be built with ``tox``: -This action is not that easy as it supposed to be. We use [Moire](http://github.com/enzet/Moire) markup and converter to automatically generate documentation for GitHub, website, and [OpenStreetMap wiki](http://wiki.openstreetmap.org/). That's why editing Markdown files is not allowed. To fix a typo, open corresponding Moire file in `doc` directory (e.g. `doc/readme.moi` for `README.md`), modify it, and run `python map_machine/moire_manager.py`. +.. code-block:: bash + $ tox -e docs diff --git a/README.rst b/README.rst index 59df07c3..f147aea1 100644 --- a/README.rst +++ b/README.rst @@ -392,4 +392,3 @@ Example of using Röntgen icons on top of the Mapnik style in JOSM. Map Paint St * ✓ Mapnik (true) * ✓ Map Machine - diff --git a/setup.py b/setup.py deleted file mode 100644 index 5fa0f33f..00000000 --- a/setup.py +++ /dev/null @@ -1,65 +0,0 @@ -""" -Map Machine project dynamic metadata. -""" -from pathlib import Path - -from setuptools import setup -from map_machine import ( - __author__, - __description__, - __doc_url__, - __email__, - __url__, - __version__, - REQUIREMENTS, -) - -with Path("README.md").open(encoding="utf-8") as input_file: - long_description: str = input_file.read() - -setup( - name="map-machine", - version=__version__, - packages=[ - "map_machine", - "map_machine.doc", - "map_machine.element", - "map_machine.feature", - "map_machine.geometry", - "map_machine.osm", - "map_machine.pictogram", - "map_machine.slippy", - "map_machine.ui", - ], - url=__url__, - project_urls={ - "Bug Tracker": f"{__url__}/issues", - }, - classifiers=[ - "Programming Language :: Python :: 3", - "License :: OSI Approved :: MIT License", - "Operating System :: OS Independent", - ], - license="MIT", - author=__author__, - author_email=__email__, - description=__description__, - long_description="Map Machine is a Python OpenStreetMap renderer and tile " - "generator with a custom set of CC-BY 4.0 icons aimed to display as many " - "map features as possible.\n\n" - f"See [full documentation]({__doc_url__}).", - long_description_content_type="text/markdown", - entry_points={ - "console_scripts": ["map-machine=map_machine.main:main"], - }, - package_data={ - "map_machine": [ - "icons/icons.svg", - "icons/config.json", - "icons/LICENSE", - "scheme/default.yml", - ], - }, - python_requires=">=3.9", - install_requires=REQUIREMENTS, -)