Release 5.0: Sphinx 👨... role, pretty tables expand tabs, drop Pyth…

…on 2.6

CHANGELOG.rst

@@ -11,6 +11,29 @@ Changelog`_ . This project adheres to `semantic versioning`_.
 .. _Keep a Changelog: http://keepachangelog.com/
 .. _semantic versioning: http://semver.org/
 
+`Release 5.0`_ (2020-02-06)
+---------------------------
+
+- Added custom ``:man:\`…\``` role for easy linking to Linux manual pages to
+  the ``humanfriendly.sphinx`` module.
+
+- Changed rendering of pretty tables to expand tab characters to spaces:
+
+  Until now pretty tables did not take the variable width of tab characters
+  into account which resulted in tables whose "line drawing characters" were
+  visually misaligned. Tabs are now expanded to spaces using
+  ``str.expandtabs()``.
+
+- Stop testing on Python 2.6 and drop official support. The world (including
+  Travis CI) has moved on and preserving Python 2.6 compatibility was clearly
+  starting to drag the project down...
+
+I decided to bump the major version number because each of these changes can be
+considered backwards incompatible in one way or another and version numbers are
+cheap anyway so there 😛.
+
+.. _Release 5.0: https://github.com/xolox/python-humanfriendly/compare/4.18...5.0
+
 `Release 4.18`_ (2019-02-21)
 ----------------------------
 

humanfriendly/__init__.py

@@ -1,7 +1,7 @@
 # Human friendly input/output in Python.
 #
 # Author: Peter Odding <peter@peterodding.com>
-# Last Change: February 21, 2019
+# Last Change: February 6, 2020
 # URL: https://humanfriendly.readthedocs.io
 
 """The main module of the `humanfriendly` package."""
@@ -40,7 +40,7 @@
 from humanfriendly.compat import is_string, monotonic
 
 # Semi-standard module versioning.
-__version__ = '4.18'
+__version__ = '5.0'
 
 # Spinners are redrawn at most this many seconds.
 minimum_spinner_interval = 0.2

humanfriendly/sphinx.py

@@ -37,6 +37,9 @@ def enable_man_role(app):
     Enable the ``:man:`` role for linking to Debian Linux manual pages.
 
     :param app: The Sphinx application object.
+
+    This function registers the :func:`man_role()` function to handle the
+    ``:man:`` role.
     """
     app.add_role("man", man_role)
 
@@ -70,7 +73,23 @@ def enable_usage_formatting(app):
 
 
 def man_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
-    """Convert a Linux manual topic to a hyperlink."""
+    """
+    Convert a Linux manual topic to a hyperlink.
+
+    Using the ``:man:`` role is very simple, here's an example:
+
+    .. code-block:: rst
+
+        See the :man:`python` documentation.
+
+    This results in the following:
+
+      See the :man:`python` documentation.
+
+    As the example shows you can use the role inline, embedded in sentences of
+    text. In the generated documentation the ``:man:`` text is omitted and a
+    hyperlink pointing to the Debian Linux manual pages is emitted.
+    """
     man_url = "https://manpages.debian.org/%s" % text
     reference = docutils.nodes.reference(rawtext, docutils.utils.unescape(text), refuri=man_url, **options)
     return [reference], []