Documenation Refactor for 1.17.1 minor release (#143)

Try hard to make the library more approachable,

- with animated screenshots,
- example codes with line-highlights, 
- flatter navigation,
- putting the easy quicktro stuff at the top of each section.
- elimited a few badges, just seemed a bit too much,
- a lot of the old material in pains.rst is recycled or gone (partly thanks to 24-bit color support)
- code-generated keyboard and color tables

.gitignore

@@ -10,6 +10,9 @@ results*.xml
 build
 dist
 docs/_build
+docs/all_the_colors.txt
+docs/all_the_keys.txt
+docs/_static/rgb
 htmlcov
 .coveralls.yml
 .DS_Store

.readthedocs.yml

@@ -0,0 +1,9 @@
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+sphinx:
+  configuration: docs/conf.py
+formats: all
+python:
+  version: 3.7
+  install:
+    - requirements: docs/requirements.txt

.travis.yml

@@ -3,7 +3,7 @@ matrix:
   fast_finish: true
   include:
     - python: 3.8
-      env: TOXENV=about,pylint,flake8,flake8_tests,sphinx COVERAGE_ID=travis-ci
+      env: TOXENV=about,pydocstyle,pylint,flake8,flake8_tests,sphinx COVERAGE_ID=travis-ci
     - python: 2.6
       env: TOXENV=py26,codecov TEST_QUICK=1 COVERAGE_ID=travis-ci
       dist: trusty

bin/bounce.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+"""Classic game of tennis."""
+# std imports
+from math import floor
+
+# local
+from blessed import Terminal
+
+
+def roundxy(x, y):
+    return int(floor(x)), int(floor(y))
+
+
+term = Terminal()
+
+x, y, xs, ys = 2, 2, 0.4, 0.3
+with term.cbreak(), term.hidden_cursor():
+    # clear the screen
+    print(term.home + term.black_on_olivedrab4 + term.clear)
+
+    # loop every 20ms
+    while term.inkey(timeout=0.02) != 'q':
+        # erase,
+        txt_erase = term.move_xy(*roundxy(x, y)) + ' '
+
+        # bounce,
+        if x >= (term.width - 1) or x <= 0:
+            xs *= -1
+        if y >= term.height or y <= 0:
+            ys *= -1
+
+        # move,
+        x, y = x + xs, y + ys
+
+        # draw !
+        txt_ball = term.move_xy(*roundxy(x, y)) + '█'
+        print(txt_erase + txt_ball, end='', flush=True)

bin/colorchart.py

@@ -1,7 +1,10 @@
 # -*- coding: utf-8 -*-
-"""Utility to show X11 colors in 24-bit and downconverted to 256, 16, and 8 color The time to
-generate the table is displayed to give an indication of how long each algorithm takes compared to
-the others."""
+"""
+Utility to show X11 colors in 24-bit and downconverted to 256, 16, and 8 colors.
+
+The time to generate the table is displayed to give an indication of how long each algorithm takes
+compared to the others.
+"""
 # std imports
 import sys
 import timeit
@@ -30,8 +33,7 @@ def sort_colors():
 
 
 def draw_chart(term):
-    """Draw a chart of each X11 color represented as in 24-bit and as downconverted to 256, 16, and
-    8 color with the currently configured algorithm."""
+    """Draw a chart of each color downconverted with selected distance algorithm."""
     sys.stdout.write(term.home)
     width = term.width
     line = ''

bin/generate-keycodes.py

@@ -0,0 +1,49 @@
+# generate keycodes for the tables in docs/keyboard.rst
+# std imports
+import os
+
+# local
+from blessed.keyboard import DEFAULT_SEQUENCE_MIXIN, CURSES_KEYCODE_OVERRIDE_MIXIN
+
+
+def is_override(key_attr_name, code):
+    return (code in [val for name, val in CURSES_KEYCODE_OVERRIDE_MIXIN] and
+            key_attr_name not in [name for name, val in CURSES_KEYCODE_OVERRIDE_MIXIN])
+
+
+def main():
+    from blessed import Terminal
+    term = Terminal()
+    csv_header = """
+.. csv-table:: All Terminal class attribute Keyboard codes, by name
+   :delim: |
+   :header: "Name", "Value", "Example Sequence(s)"
+
+"""
+    fname = os.path.abspath(
+        os.path.join(os.path.dirname(__file__), os.pardir, 'docs', 'all_the_keys.txt'))
+    with open(fname, 'w') as fout:
+        print(f"write: {fout.name}")
+        fout.write(csv_header)
+        for key_attr_name in sorted([
+                attr for attr in dir(term) if attr.startswith('KEY_')
+        ]):
+            # filter away F23-F63 (lol)
+            if key_attr_name.startswith('KEY_F'):
+                maybe_digit = key_attr_name[len('KEY_F'):]
+                if maybe_digit.isdigit() and int(maybe_digit) > 23:
+                    continue
+            code = getattr(term, key_attr_name)
+            repr_sequences = []
+            for (seq, value) in DEFAULT_SEQUENCE_MIXIN:
+                if value == code:
+                    repr_sequences.append(repr(seq))
+            txt_sequences = ', '.join(repr_sequences).replace('\\', '\\\\')
+            fout.write(f'    {key_attr_name} | {code}')
+            if txt_sequences:
+                fout.write(f'| {txt_sequences}')
+            fout.write('\n')
+
+
+if __name__ == '__main__':
+    main()

bin/generate-x11-colorchart.py

@@ -0,0 +1,84 @@
+# generate images and tables for inclusion in docs/colors.rst
+# std imports
+import os
+import re
+import math
+import colorsys
+from functools import reduce
+
+# 3rd party
+from PIL import Image
+
+# local
+from blessed.colorspace import X11_COLORNAMES_TO_RGB
+
+rgb_folder = os.path.abspath(
+    os.path.join(os.path.dirname(__file__), os.pardir, 'docs', '_static', 'rgb'))
+
+color_alias_fmt = """
+.. |{color_name}| image:: _static/rgb/{color_name}.png
+   :width: 48pt
+   :height: 12pt"""
+
+csv_table = """.. csv-table:: All Terminal colors, by name
+   :header: "Name", "Image", "R", "G", "B", "H", "S", "V"
+"""
+
+
+def sort_colors():
+    colors = {}
+    for color_name, rgb_color in X11_COLORNAMES_TO_RGB.items():
+        if rgb_color in colors:
+            colors[rgb_color].append(color_name)
+        else:
+            colors[rgb_color] = [color_name]
+
+    def sortby_hv(rgb_item):
+        # sort by hue rounded to nearest %,
+        # then by color name & number
+        # except shades of grey -- by name & number, only
+        rgb, name = rgb_item
+        digit = 0
+        match = re.match(r'(.*)(\d+)', name[0])
+        if match is not None:
+            name = match.group(1)
+            digit = int(match.group(2))
+        else:
+            name = name[0]
+        hash_name = reduce(int.__mul__, map(ord, name))
+
+        hsv = colorsys.rgb_to_hsv(*rgb)
+        if rgb[0] == rgb[1] == rgb[2]:
+            return 100, hsv[2], hash_name, digit
+
+        return int(math.floor(hsv[0] * 100)), hash_name, digit, hsv[2]
+
+    return sorted(colors.items(), key=sortby_hv)
+
+
+def main():
+    aliases, csv_rows = '', ''
+    for rgb, x11_colors in sort_colors():
+        x11_color = sorted(x11_colors)[0]
+        fname = os.path.join(rgb_folder, f'{x11_color}.png')
+        if not os.path.exists(os.path.join(fname)):
+            img = Image.new('RGB', (1, 1), color=rgb)
+            img.save(fname)
+            print(f'write: {fname}')
+        aliases += color_alias_fmt.format(color_name=x11_color)
+        hsv = colorsys.rgb_to_hsv(*rgb)
+        csv_rows += ('   '
+                     f'{x11_color}, |{x11_color}|, '
+                     f'{rgb[0]/255:0.1%}, {rgb[1]/255:0.1%}, {rgb[2]/255:0.1%}, '
+                     f'{hsv[0]:0.1%}, {hsv[1]:0.1%}, {hsv[2]/255:0.1%}\n')
+
+    output = aliases + '\n\n' + csv_table + '\n' + csv_rows
+    filepath_txt = os.path.abspath(os.path.join(os.path.dirname(__file__), os.path.pardir, 'docs',
+                                                'all_the_colors.txt'))
+    with open(filepath_txt, 'w') as fout:
+        print(f'write: {fout.name}')
+        fout.write(output.lstrip())
+
+
+if __name__ == '__main__':
+    main()

bin/keymatrix.py

@@ -128,7 +128,7 @@ def main():
             inps.append(inp)
 
     with term.cbreak():
-        echo(term.move_yx(term.height))
+        echo(term.move_y(term.height))
         echo(
             u'{term.clear_eol}Your final score was {score} '
             u'at level {level}{term.clear_eol}\n'

bin/x11_colorpicker.py

@@ -1,21 +1,43 @@
 # std imports
+import re
+import math
 import colorsys
+from functools import reduce
 
 # local
 import blessed
+from blessed.colorspace import X11_COLORNAMES_TO_RGB
 
 
 def sort_colors():
     colors = {}
-    for color_name, rgb_color in blessed.colorspace.X11_COLORNAMES_TO_RGB.items():
+    for color_name, rgb_color in X11_COLORNAMES_TO_RGB.items():
         if rgb_color in colors:
             colors[rgb_color].append(color_name)
         else:
             colors[rgb_color] = [color_name]
 
-    return sorted(colors.items(),
-                  key=lambda rgb: colorsys.rgb_to_hsv(*rgb[0]),
-                  reverse=True)
+    def sortby_hv(rgb_item):
+        # sort by hue rounded to nearest %,
+        # then by color name & number
+        # except shades of grey -- by name & number, only
+        rgb, name = rgb_item
+        digit = 0
+        match = re.match(r'(.*)(\d+)', name[0])
+        if match is not None:
+            name = match.group(1)
+            digit = int(match.group(2))
+        else:
+            name = name[0]
+        hash_name = reduce(int.__mul__, map(ord, name))
+
+        hsv = colorsys.rgb_to_hsv(*rgb)
+        if rgb[0] == rgb[1] == rgb[2]:
+            return 100, hsv[2], hash_name, digit
+
+        return int(math.floor(hsv[0] * 100)), hash_name, digit, hsv[2]
+
+    return sorted(colors.items(), key=sortby_hv)
 
 
 HSV_SORTED_COLORS = sort_colors()

blessed/__init__.py

@@ -18,4 +18,4 @@
                       'support due to http://bugs.python.org/issue10570.')
 
 __all__ = ('Terminal',)
-__version__ = '1.17.0'
+__version__ = '1.17.1'

blessed/terminal.py

@@ -531,7 +531,7 @@ def get_location(self, timeout=None):
         :arg float timeout: Return after time elapsed in seconds with value
             ``(-1, -1)`` indicating that the remote end did not respond.
         :rtype: tuple
-        :returns: cursor position as tuple in form of (row, column).
+        :returns: cursor position as tuple in form of ``(x, y)``.
 
         The location of the cursor is determined by emitting the ``u7``
         terminal capability, or VT100 `Query Cursor Position

docs/_templates/layout.html

@@ -0,0 +1,8 @@
+{% extends "!layout.html" %}
+  {% block footer %} {{ super() }}
+
+  <style>
+    .wy-nav-content { max-width: 900px; }
+  </style>
+
+{% endblock %}

docs/api.rst

@@ -1,59 +1,8 @@
 API Documentation
 =================
 
-color.py
---------
+.. toctree::
+   :maxdepth: 3
+   :glob:
 
-.. automodule:: blessed.color
-   :members:
-   :undoc-members:
-   :private-members:
-
-colorspace.py
--------------
-
-.. automodule:: blessed.colorspace
-   :members:
-   :undoc-members:
-   :private-members:
-
-formatters.py
--------------
-
-.. automodule:: blessed.formatters
-   :members:
-   :undoc-members:
-   :private-members:
-   :special-members: __call__
-.. autodata:: COLORS
-.. autodata:: COMPOUNDABLES
-
-keyboard.py
------------
-
-.. automodule:: blessed.keyboard
-   :members:
-   :undoc-members:
-   :private-members:
-   :special-members: __new__
-.. autofunction:: _alternative_left_right
-.. autodata:: DEFAULT_SEQUENCE_MIXIN
-.. autodata:: CURSES_KEYCODE_OVERRIDE_MIXIN
-.. autodata:: _CURSES_KEYCODE_ADDINS
-
-sequences.py
-------------
-
-.. automodule:: blessed.sequences
-   :members:
-   :undoc-members:
-   :private-members:
-
-terminal.py
------------
-
-.. automodule:: blessed.terminal
-   :members:
-   :undoc-members:
-   :special-members: __getattr__
-.. autodata:: _CUR_TERM
+   api/*

docs/api/color.rst

@@ -0,0 +1,7 @@
+color.py
+--------
+
+.. automodule:: blessed.color
+   :members:
+   :undoc-members:
+   :private-members:

docs/api/colorspace.rst

@@ -0,0 +1,6 @@
+colorspace.py
+-------------
+
+.. automodule:: blessed.colorspace
+   :members:
+   :private-members:

docs/api/formatters.rst

@@ -0,0 +1,10 @@
+formatters.py
+-------------
+
+.. automodule:: blessed.formatters
+   :members:
+   :undoc-members:
+   :private-members:
+   :special-members: __call__
+.. autodata:: COLORS
+.. autodata:: COMPOUNDABLES