From 589f8f129d221f7041fb3388c0e0bb5ba2671e50 Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Tue, 17 Sep 2024 17:03:01 +0200 Subject: [PATCH] update README and reinstate man page creation --- README.md | 33 ++++++++++++++++---------- README.rst | 7 +++--- mkdocs.yaml | 5 +++- tools/pyosmium-get-changes | 28 +++++++++++----------- tools/pyosmium-up-to-date | 48 ++++++++++++++++++++------------------ 5 files changed, 66 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index fb85f6f4..d809a3ad 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ manner. ## Installation -Pyosmium works with Python >= 3.6. Pypy is known to not work. +Pyosmium works with Python >= 3.7. Pypy is known to not work. ### Using Pip @@ -36,14 +36,15 @@ pyosmium has the following dependencies: * [libosmium](https://github.com/osmcode/libosmium) >= 2.16.0 * [protozero](https://github.com/mapbox/protozero) * [cmake](https://cmake.org/) - * [Pybind11](https://github.com/pybind/pybind11) >= 2.2 + * [Pybind11](https://github.com/pybind/pybind11) >= 2.7 * [expat](https://libexpat.github.io/) * [libz](https://www.zlib.net/) * [libbz2](https://www.sourceware.org/bzip2/) * [Boost](https://www.boost.org/) variant and iterator >= 1.41 * [Python Requests](https://docs.python-requests.org/en/master/) * Python setuptools - * a recent C++ compiler (Clang 3.4+, GCC 4.8+) + * [Requests](https://requests.readthedocs.io) + * a C++17-compatible compiler (Clang 7+, GCC 8+) ### Compiling from Source @@ -76,7 +77,7 @@ run: To compile and install the bindings, run - pip install [--user] . + pip install . ## Examples @@ -102,21 +103,29 @@ The test suite can be run with: ## Documentation -To build the documentation you need [Sphinx](http://sphinx-doc.org/) -and the [autoprogram extension](https://pythonhosted.org/sphinxcontrib-autoprogram/) -On Debian/Ubuntu install `python-sphinx sphinxcontrib-autoprogram` -or `python3-sphinx python3-sphinxcontrib.autoprogram`. +To build the documentation you need [mkdocs](https://www.mkdocs.org/) +with the [mkdocstrings extension](https://mkdocstrings.github.io/) +and the [material theme](https://squidfunk.github.io/mkdocs-material/). +On Debian/Ubuntu install -First compile the bindings as described above and then run: + sudo apt-get install mkdocs mkdocstrings mkdocstrings-python-handlers\ + mkdocs-material mkdocs-material-extensions - cd doc - make html +To build the documentation run: + + mkdocs build + +or to few it locally, you can use: + + mkdocs serve For building the man pages for the tools run: - cd doc + cd docs make man +The man pages can be found in docs/man. + ## Bugs and Questions If you find bugs or have feature requests, please report those in the diff --git a/README.rst b/README.rst index 53cc3757..4fa45337 100644 --- a/README.rst +++ b/README.rst @@ -24,7 +24,7 @@ development packages for these libraries. On Debian/Ubuntu do:: libexpat1-dev zlib1g-dev libbz2-dev -Python >= 3.6 is supported. Pypy is known not to work. +Python >= 3.7 is supported. Pypy is known not to work. Documentation ============= @@ -34,12 +34,11 @@ The documentation for the latest release is available at If you find bugs or have feature requests, please report those in the `Github issue tracker`_. For general questions about using pyosmium you -can contanct the `OSM development mailing list`_ or ask on `OSM help`_. +can contanct the `OSM forum`_. .. _osmcode.org: http://docs.osmcode.org/pyosmium/latest .. _Github issue tracker: https://github.com/osmcode/pyosmium/issues/ -.. _OSM development mailing list: https://lists.openstreetmap.org/listinfo/dev -.. _OSM help: https://help.openstreetmap.org/ +.. _OSM forum: https://community.openstreetmap.org/ Examples ======== diff --git a/mkdocs.yaml b/mkdocs.yaml index a8f0b12b..faca0082 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -10,6 +10,7 @@ theme: - privacy copyright: Copyright © Sarah Hoffmann repo_url: https://github.com/osmcode/pyosmium +site_url: https://osmcode.org/pyosmium/ nav: - index.md - 'User Manual': @@ -71,14 +72,16 @@ markdown_extensions: extra_css: - css/mkdocstrings.css - css/extra.css +site_dir: site-html plugins: - search - autorefs -# - mkdocs-jupyter + - mkdocs-jupyter - mkdocstrings: default_handler: python handlers: python: + paths: [src] options: allow_inspection: false heading_level: 3 diff --git a/tools/pyosmium-get-changes b/tools/pyosmium-get-changes index 0375ab9d..3c901055 100755 --- a/tools/pyosmium-get-changes +++ b/tools/pyosmium-get-changes @@ -116,17 +116,15 @@ def write_end_sequence(fname, seqid): fd.write(str(seqid)) def get_arg_parser(from_main=False): - def h(s): - return re.sub(r'\s\s+' , " ", s) - - parser = ArgumentParser(description=__doc__, + parser = ArgumentParser(prog='pyosmium-get-changes', + description=__doc__, usage=None if from_main else 'pyosmium-get-changes [options]', formatter_class=RawDescriptionHelpFormatter) parser.add_argument('-v', dest='loglevel', action='count', default=0, help='Increase verbosity (can be used multiple times)') parser.add_argument('-o', '--outfile', dest='outfile', - help=h("""Name of diff output file. If omitted, only the - sequence ID will be printed where updates would start.""")) + help='Name of diff output file. If omitted, only the ' + 'sequence ID will be printed where updates would start.') parser.add_argument('--format', dest='outformat', metavar='FORMAT', help="Format the data should be saved in.") parser.add_argument('--server', action='store', dest='server_url', @@ -134,8 +132,8 @@ def get_arg_parser(from_main=False): parser.add_argument('--diff-type', action='store', dest='server_diff_type', help='File format used by the replication server (default: osc.gz)') parser.add_argument('--cookie', dest='cookie', - help="""Netscape-style cookie jar file to read cookies from - and where received cookies will be written to.""") + help='Netscape-style cookie jar file to read cookies from ' + 'and where received cookies will be written to.') parser.add_argument('-s', '--size', dest='outsize', type=int, default=100, help='Maximum data to load in MB (default: 100MB).') group = parser.add_mutually_exclusive_group() @@ -148,15 +146,15 @@ def get_arg_parser(from_main=False): group.add_argument('-O', '--start-osm-data', dest='start_file', metavar='OSMFILE', help='start at the date of the newest OSM object in the file') parser.add_argument('-f', '--sequence-file', dest='seq_file', - help=h("""Sequence file. If the file exists, then updates - will start after the id given in the file. At the - end of the process, the last sequence ID contained - in the diff is written.""")) + help='Sequence file. If the file exists, then updates ' + 'will start after the id given in the file. At the ' + 'end of the process, the last sequence ID contained ' + 'in the diff is written.') parser.add_argument('--ignore-osmosis-headers', dest='ignore_headers', action='store_true', - help=h("""When determining the start from an OSM file, - ignore potential replication information in the - header and search for the newest OSM object.""")) + help='When determining the start from an OSM file, ' + 'ignore potential replication information in the ' + 'header and search for the newest OSM object.') parser.add_argument('-d', '--no-deduplicate', action='store_false', dest='simplify', help='Do not deduplicate diffs.') parser.add_argument('--socket-timeout', dest='socket_timeout', type=int, default=60, diff --git a/tools/pyosmium-up-to-date b/tools/pyosmium-up-to-date index 60e7bdac..53fb90d2 100755 --- a/tools/pyosmium-up-to-date +++ b/tools/pyosmium-up-to-date @@ -25,8 +25,8 @@ because the size limit has been reached or there was a network error which could not be resolved). Any other error results in a return code larger than 1. The output file is guaranteed to be unmodified in that case. -Some OSM data sources require a cookie to be sent with the HTTP requests. -Pyosmium-up-to-date does not fetch the cookie from these services for you. +Some OSM data sources require a cookie to be sent with the HTTP requests. +pyosmium-up-to-date does not fetch the cookie from these services for you. However, it can read cookies from a Netscape-style cookie jar file, send these cookies to the server and will save received cookies to the jar file. """ @@ -181,46 +181,48 @@ def compute_start_point(options): return url, seq, ts def get_arg_parser(from_main=False): - def h(s): - return re.sub(r'\s\s+' , " ", s) - parser = ArgumentParser(description=__doc__, + parser = ArgumentParser(prog='pyosmium-up-to-date', + description=__doc__, usage=None if from_main else 'pyosmium-up-to-date [options] ', formatter_class=RawDescriptionHelpFormatter) parser.add_argument('-v', dest='loglevel', action='count', default=0, - help='Increase verbosity (can be used multiple times)') + help='Increase verbosity (can be used multiple times).') parser.add_argument('infile', metavar='', help="OSM file to update") parser.add_argument('-o', '--outfile', dest='outfile', - help=h("""Name output of file. If missing, the input file - will be overwritten.""")) + help='Name output of file. If missing, the input file ' + 'will be overwritten.') parser.add_argument('--format', dest='outformat', metavar='FORMAT', - help="Format the data should be saved in.") + help='Format the data should be saved in. ' + 'Usually determined from file name.') parser.add_argument('--server', action='store', dest='server_url', - help=h("""Base URL of the replication server. Default: - 'https://planet.osm.org/replication/hour/' - (hourly diffs from osm.org).""")) + help='Base URL of the replication server. Default: ' + 'https://planet.osm.org/replication/hour/ ' + '(hourly diffs from osm.org)') parser.add_argument('-s', '--size', dest='outsize', metavar='SIZE', type=int, default=1024, - help='Maximum size of change to apply at once in MB. Default: 1GB.') + help='Maximum size of change to apply at once in MB. Default: 1GB') parser.add_argument('--tmpdir', dest='tmpdir', - help='Directory to use for temporary files. Default: directory of input file') + help='Directory to use for temporary files. ' + 'Usually the directory of input file is used.') parser.add_argument('--ignore-osmosis-headers', dest='ignore_headers', action='store_true', - help=h("""Ignore potential replication information in the - header of the input file and search for the - newest OSM object in the file instead.""")) + help='Ignore potential replication information in the ' + 'header of the input file and search for the ' + 'newest OSM object in the file instead.') parser.add_argument('-b', '--wind-back', dest='wind_back', type=int, default=60, - help=h("""Number of minutes to start downloading before - the newest addition to input data. (Ignored when - the file contains a sequence ID.) Default: 60.""")) + help='Number of minutes to start downloading before ' + 'the newest addition to input data. (Ignored when ' + 'the file contains a sequence ID.) Default: 60') parser.add_argument('--force-update-of-old-planet', action='store_true', dest='force_update', help="Apply update even if the input data is really old.") parser.add_argument('--cookie', dest='cookie', - help="""Netscape-style cookie jar file to read cookies from and where - received cookies will be written to.""") + help='Netscape-style cookie jar file to read cookies from and where ' + 'received cookies will be written to.') parser.add_argument('--socket-timeout', dest='socket_timeout', type=int, default=60, help='Set timeout for file downloads.') - parser.add_argument('--version', action='version', version='pyosmium ' + pyosmium_release) + parser.add_argument('--version', action='version', + version='pyosmium ' + pyosmium_release) return parser