update README and reinstate man page creation

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

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
 ========

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

tools/pyosmium-get-changes

@@ -116,26 +116,24 @@ 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',
                         help='Base URL of the replication server')
     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,

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] <osm file>',
                             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='<osm file>', 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