diff --git a/AUTHORS b/AUTHORS new file mode 100644 index 0000000..bfeece9 --- /dev/null +++ b/AUTHORS @@ -0,0 +1,147 @@ +Authors +******* + +IMPORTANT: THIS DOCUMENT IS AUTOGENERATED. To update it, modify +docs/authors/index.rst in the QuickTile source distribution and run +docs/update_authors.sh + +NOTE: Due to limitations in Sphinx's generation of text output, +attribution URLs are missing from this version and the textual +rendering of inline images is less than ideal. The HTML version +included in the QuickTile manual should be preferred where possible. + + +The Program +=========== + +QuickTile is primarily the work of Stephan Sokolow, however, it has +received various contributions over the years. + +Thanks go out to the following people: + +David Stygstra + Generalized the "move-to-center" command into the "move-to-*" + family of commands. + +Justin + Added the "horizontal-maximize", "vertical-maximize", and "move-to- + center" commands. + +Matthias Putz + Fixed use of an uninitialized variable in a difficult-to-trigger + failure case. + +Max Weiß + + * Added the "KEYLOOKUP" dict to compensate for un-intuitive + omissions for the symbol names of common keys. + + * Reworked the shebang to address the period when some Linux + distros lacked a **python2** binary while others linked + **python** to Python 3. + +Oliver Gerlich + Corrected an omission on the list of dependencies for CentOS 7 and + possibly other Red Hat-family distros. + +Stéphane Gourichon + + * Researched how to create ".deb" packages + + * Wrote "recompile_local_debian_package.sh" + + * Set up the necessary package metadata for building a ".deb". + +Stuart Axelbrooke + Corrected a flaw in the window-tiling heuristics which prevented + them from functioning correctly on especially large monitors. + +Valdis Vitolins + Added an omitted dependency on "python-setuptools" to "README.rst" + +Valentin Agachi + Corrected window-layout calculations to use "round()" for pixel + values. + +Yuting/Tim Xiao + Made the window-tiling heuristics more robust. + + +The Manual +========== + +With the following exceptions, all text and illustrations in the +manual are copyright Stephan Sokolow. + +It should be assumed that, as the contents of the API documentation +section are extracted from the source code, the copyright of a given +entry will be the same as the code it describes. + +The text of the Alabaster theme for Sphinx, and any generated text +inserted by Sphinx are copyright their respective rightsholders. + + +Imagery +------- + +The following illustrations are copyright David Stygstra: + +* "bordered.svg" + +* "bottom-left.svg" + +* "bottom-right.svg" + +* "bottom.svg" + +* "fullscreen.svg" + +* "horizontal-maximize.svg" + +* "left.svg" + +* "maximize.svg" + +* "middle.svg" + +* "minimize.svg" + +* "move-to-bottom-left.svg" + +* "move-to-bottom-right.svg" + +* "move-to-bottom.svg" + +* "move-to-center.svg" + +* "move-to-left.svg" + +* "move-to-right.svg" + +* "move-to-top-left.svg" + +* "move-to-top-right.svg" + +* "move-to-top.svg" + +* "right.svg" + +* "shade.svg" + +* "top-left.svg" + +* "top-right.svg" + +* "top.svg" + +* "vertical-maximize.svg" + +[image: bug.png][image] and [image: wrench.png][image] from the Silk +Icons set by Mark James are used under the Creative Commons +Attribution 2.5 license. + +The [image: GPLv2+ License][image] badge is a locally cached copy of +an SVG file generated by Shields.io. + +All other favicons and logos are copyright their respective owners and +used only to display favicon-style links to their owners' websites. diff --git a/docs/AUTHORS b/docs/AUTHORS deleted file mode 100644 index b0e4053..0000000 --- a/docs/AUTHORS +++ /dev/null @@ -1,43 +0,0 @@ -Unless otherwise stated, all text and illustrations in this manual are -copyright Stephan Sokolow. - -The following illustrations are copyright -David Stygstra (https://github.com/stygstra): - bordered.svg - bottom-left.svg - bottom-right.svg - bottom.svg - fullscreen.svg - horizontal-maximize.svg - left.svg - maximize.svg - middle.svg - minimize.svg - move-to-bottom-left.svg - move-to-bottom-right.svg - move-to-bottom.svg - move-to-center.svg - move-to-left.svg - move-to-right.svg - move-to-top-left.svg - move-to-top-right.svg - move-to-top.svg - right.svg - shade.svg - top-left.svg - top-right.svg - top.svg - vertical-maximize.svg - -bug.png and wrench.png from the Silk Icons set by Mark James, available at -http://www.famfamfam.com/lab/icons/silk/ -are used under the Creative Commons Attribution 2.5 license. - -The GPLv2+ License badge is a locally cached copy of an SVG file generated by -Shields.io. - -All other favicons and logos are copyright their respective owners and used -only to display favicon-style links to their owners' websites. - -The text of the Alabaster theme for Sphinx, and any generated text inserted by -Sphinx are copyright their respective rightsholders. diff --git a/docs/authors/index.rst b/docs/authors/index.rst new file mode 100644 index 0000000..db2a582 --- /dev/null +++ b/docs/authors/index.rst @@ -0,0 +1,154 @@ +.. + IMPORTANT: Sphinx's text output silently erases hyperlinks without + presenting the URLs in another fashion and renders inline images in a + somewhat ugly style. Please bear this in mind when editing. + +Authors +======= + +.. only:: text + + IMPORTANT: THIS DOCUMENT IS AUTOGENERATED. To update it, modify + docs/authors/index.rst in the QuickTile source distribution and run + docs/update_authors.sh + + NOTE: Due to limitations in Sphinx's generation of text output, attribution + URLs are missing from this version and the textual rendering of inline + images is less than ideal. The HTML version included in the QuickTile + manual should be preferred where possible. + +The Program +----------- + +QuickTile is primarily the work of `Stephan Sokolow`_, however, it has received +various contributions over the years. + +Thanks go out to the following people: + +`David Stygstra`_ + Generalized the ``move-to-center`` command into the ``move-to-*`` family + of commands. + +Justin + Added the ``horizontal-maximize``, ``vertical-maximize``, and + ``move-to-center`` commands. + +Matthias Putz + Fixed use of an uninitialized variable in a difficult-to-trigger failure + case. + +`Max Weiß`_ + + * Added the ``KEYLOOKUP`` dict to compensate for un-intuitive omissions for + the symbol names of common keys. + * Reworked the shebang to address the period when some Linux distros lacked + a :command:`python2` binary while others linked :command:`python` to + Python 3. + +`Oliver Gerlich`_ + Corrected an omission on the list of dependencies for CentOS 7 and possibly + other Red Hat-family distros. + +`Stéphane Gourichon`_ + + * Researched how to create ``.deb`` packages + * Wrote :file:`recompile_local_debian_package.sh` + * Set up the necessary package metadata for building a ``.deb``. + +`Stuart Axelbrooke`_ + Corrected a flaw in the window-tiling heuristics which prevented them + from functioning correctly on especially large monitors. + +`Valdis Vitolins`_ + Added an omitted dependency on ``python-setuptools`` to :file:`README.rst` + +`Valentin Agachi`_ + Corrected window-layout calculations to use :py:func:`round` for pixel + values. + +`Yuting/Tim Xiao`_ + Made the window-tiling heuristics more robust. + +The Manual +---------- + +With the following exceptions, all text and illustrations in the manual are +copyright `Stephan Sokolow`_. + +It should be assumed that, as the contents of the API documentation section are +extracted from the source code, the copyright of a given entry will be the same +as the code it describes. + +The text of the Alabaster_ theme for Sphinx_, and any generated text inserted +by Sphinx are copyright their respective rightsholders. + +Imagery +^^^^^^^ + +The following illustrations are copyright `David Stygstra`_: + +* ``bordered.svg`` +* ``bottom-left.svg`` +* ``bottom-right.svg`` +* ``bottom.svg`` +* ``fullscreen.svg`` +* ``horizontal-maximize.svg`` +* ``left.svg`` +* ``maximize.svg`` +* ``middle.svg`` +* ``minimize.svg`` +* ``move-to-bottom-left.svg`` +* ``move-to-bottom-right.svg`` +* ``move-to-bottom.svg`` +* ``move-to-center.svg`` +* ``move-to-left.svg`` +* ``move-to-right.svg`` +* ``move-to-top-left.svg`` +* ``move-to-top-right.svg`` +* ``move-to-top.svg`` +* ``right.svg`` +* ``shade.svg`` +* ``top-left.svg`` +* ``top-right.svg`` +* ``top.svg`` +* ``vertical-maximize.svg`` + +|bug.png| and |wrench.png| from the `Silk Icons`_ set by `Mark James`_ +are used under the `Creative Commons Attribution 2.5`_ license. + + +The |license.svg| badge is a locally cached copy of an SVG file generated by +Shields.io_. + +All other favicons and logos are copyright their respective owners and used +only to display favicon-style links to their owners' websites. + +.. |bug.png| image:: ../_static/contrib_box/bug.png +.. |wrench.png| image:: ../wrench.png + +.. |license.svg| image:: ../_static/license.svg + :alt: GPLv2+ License + +.. _Alabaster: https://alabaster.readthedocs.io/ +.. _Creative Commons Attribution 2.5: https://creativecommons.org/licenses/by/2.5/ +.. _David Stygstra: https://github.com/stygstra +.. _Mark James: https://twitter.com/markjames +.. _Max Weiß: https://github.com/wmax +.. _Oliver Gerlich: https://github.com/oliver +.. _Shields.io: https://shields.io/ +.. _Silk Icons: http://www.famfamfam.com/lab/icons/silk/ +.. _Sphinx: https://alabaster.readthedocs.io/ +.. _Stephan Sokolow: http://ssokolow.com/ +.. _Stéphane Gourichon: https://github.com/fidergo-stephane-gourichon +.. _Stuart Axelbrooke: https://github.com/soaxelbrooke +.. _Valdis Vitolins: https://github.com/valdisvi +.. _Valentin Agachi: https://github.com/avaly +.. _Yuting/Tim Xiao: https://github.com/txiao + +.. + NOTE: For "Yuting/Tim Xiao", the commits are signed "Yuting Xiao" but the + name on the associated GitHub account has since been changed to "Tim Xiao". + I am operating on the assumption that this is a case of "Yuting" being the + contributor's legal name and "Tim" being a nickname the contributor has + taken to more easily interact with peers... it's apparently a common + practice. diff --git a/docs/conf.py b/docs/conf.py index 3484808..c7507fc 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -89,7 +89,7 @@ def setup(app): # General information about the project. project = u'QuickTile' author = u'Stephan Sokolow' -copyright = u'2009-2020, Stephan Sokolow' # pylint: disable=W0622 +copyright = u'2009-2020, Stephan Sokolow et al' # pylint: disable=W0622 # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/docs/developing.rst b/docs/developing.rst index 797d957..405b46b 100644 --- a/docs/developing.rst +++ b/docs/developing.rst @@ -308,6 +308,56 @@ comfortable edit-test cycle. In lieu of a proper functional test suite, please manually execute all tiling commands which rely on code you've touched and watch for misbehaviour. +Adding Yourself to the :file:`AUTHORS` List +------------------------------------------- + +When making a contribution, please also add yourself to the +:doc:`authors/index` section and regenerate the :file:`AUTHORS` file in the +root of the project. + +This can be done as follows: + +1. Edit :file:`docs/authors/index.rst` +2. Regenerate the HTML version of the documentation and verify that it looks + right. (Run :command:`make html` from inside the :file:`docs` folder.) +3. Run :file:`./docs/update_authors.sh` to regenerate :file:`AUTHORS` +4. Verify that :file:`AUTHORS` looks right. +5. Commit your changes. + +Additions to the "The Program" section should be phrased so that reading the +definition list title and body together form a sentence in the `simple past +tense`_. However, the body portion should still be capitalized as if it is +a complete sentence. + +Please combine related changes into a single high-level description of the user-visible changes. This rule may be relaxed when it would unfairly downplay the +amount of work involved. + +Please try to make proper use of Sphinx markup to indicate things such as +command and function names. Constructs such as ``:py:mod:`round``` may be used +to reference identifiers within dependencies but be aware that, because +generation of :file:`AUTHORS` considers the document in isolation, +markup which attempts to generate cross-references to the rest of the manual +will trigger warnings when :file:`update_authors.sh` is run and may *not* be +be used. + +.. highlight:: rst + +A Good Example:: + + Yuting/Tim Xiao + Made the wndow-tiling heuristics more robust. + +A Bad Example:: + + Yuting/Tim Xiao + + * Increase closest-dimension matching fuzziness to 100px. + * Update min-distance calculation in cycleDimensions to use + lengths instead of area. + * Always use the first given configuration for untiled windows. + +.. highlight:: default + .. _AdvanceCOMP: https://www.advancemame.it/comp-readme .. _ALE: https://github.com/dense-analysis/ale/ .. _Bandit: https://github.com/PyCQA/bandit @@ -325,6 +375,7 @@ commands which rely on code you've touched and watch for misbehaviour. .. _OptiPNG: http://optipng.sourceforge.net/ .. _PyLint: https://www.pylint.org/ .. _pull request: https://github.com/ssokolow/quicktile/pulls +.. _simple past tense: https://en.wikipedia.org/wiki/Simple_past .. _Sphinx: https://www.sphinx-doc.org/ .. _sphinx-autodoc-typehints: https://pypi.org/project/sphinx-autodoc-typehints/ .. _sphinxcontrib-autoprogram: https://pypi.org/project/sphinxcontrib-autoprogram/ diff --git a/docs/index.rst b/docs/index.rst index 2299c02..b20bf85 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,6 +35,7 @@ Manual Contents: faq apidocs/index developing + authors/index * :ref:`modindex` * :ref:`genindex` diff --git a/docs/update_authors.sh b/docs/update_authors.sh new file mode 100755 index 0000000..c8d02ff --- /dev/null +++ b/docs/update_authors.sh @@ -0,0 +1,9 @@ +#!/bin/sh + +TMP_TARGET="_build/authors" + +cd "$(dirname "$(readlink -f "$0")")" + +rm -rf "$TMP_TARGET/index.txt" +sphinx-build -b text -c . authors "$TMP_TARGET" +mv $TMP_TARGET/index.txt ../AUTHORS