'''
# Design

`esy.osm.shape` is designed as a library with the purpose of converting
[OpenStreetMap](https://www.openstreetmap.org) primitives to
[shapely](https://shapely.readthedocs.io/en/latest/) objects.

# Development

Development should advance via merge requests. New functionality should include
tests written in `doctest` and documented using `pdoc`.

To execute tests run:

```console
$ PYTHONPATH=src python -m doctest src/esy/osm/shape/*.py
```

To compute the code coverage of tests run:

```console
$ PYTHONPATH=src coverage run --source src -m doctest src/esy/osm/shape/*.py
```

To check coverage run:

```console
$ coverage report
```

To build the documentation run (note that the documentation depends on figures
generated by the doctests above):

```console
$ PYTHONPATH=src pdoc --output public esy.osm.shape
```

## Quality assurance

The code quality is assured exclusively using `doctest`. All tests are written
in docstrings. While writing doctests is a bit cumbersome, it motivates short
and concise tests which in-turn supports a modular design. As all code examples
are automatically tested, a consistent documentation is guaranteed.

To avoid inconsistencies and duplication, the README page is an almost verbatim
copy of the `esy.osm.shape.__init__.__doc__` string. The `check_readme`
function will ensure that this is the case.
'''

import doctest


def check_readme():
    '''
    Ensures README.md is uptodate with module documentation.

    >>> check_readme()
    '''
    import difflib, esy.osm.shape
    # Replace links to images with absolute urls. This is required for them to
    # show up at PyPI.
    doc = esy.osm.shape.__doc__.replace(
        '../../../../',
        'https://gitlab.com/dlr-ve-esy/esy-osm-shape/-/raw/main/'
    ).lstrip()
    readme = open('README.md').read()
    for line in difflib.unified_diff(
        doc.splitlines(keepends=True), readme.splitlines(keepends=True),
        '<docstring>', 'README.md'
    ):
        # Add a prefix character to suppress doctests <BLANKLINE> markers.
        print('|', line, end='') #pragma: nocover
