Merge branch 'f/qa_frivolity'

* f/qa_frivolity:
  Keep ' and " uniform
  Include alt text for travis image
  Bump copyright years
  Remove unused module data from docstring
  Update nose2 example
  Use console lexer for example sessions
  Fix footnote link in fun document
  Fix comment syntax in FAQ document
  Sync Sphinx config across projects
  Include members in autodoc defaults
  Tiny grammar fix
  Minor changes to make flake8 happier
  Switch to extlinks for PyPI links
  Improve PEP-257 compliance
  Re-wrap docs
  Update API stability notice for 1.0
  Remove silly usage example
  Use abbr tags in docs

README.rst

@@ -1,8 +1,9 @@
-``pyisbn`` - A module for working with 10- and 13-digit ISBNs
-=============================================================
+``pyisbn`` - A module for working with 10- and 13-digit |ISBNs|
+===============================================================
 
 .. image:: https://secure.travis-ci.org/JNRowe/pyisbn.png?branch=master
    :target: https://travis-ci.org/JNRowe/pyisbn
+   :alt: Test state on master
 
 .. image:: https://img.shields.io/coveralls/JNRowe/pyisbn/master.svg?style=plastic
    :target: https://coveralls.io/repos/JNRowe/pyisbn
@@ -13,8 +14,8 @@ Introduction
 
 ``pyisbn`` is a `GPL v3`_ licensed module for working with various book
 identification numbers.  It includes functions for conversion, verification and
-generation of checksums.  It also includes basic classes for representing ISBNs
-as objects.
+generation of checksums.  It also includes basic classes for representing
+|ISBNs| as objects.
 
 See the ``doc`` directory for installation instructions and usage information,
 you can also `view the content online`_.
@@ -44,10 +45,8 @@ The simplest way to show how ``pyisbn`` works is by example, and here goes::
     True
     >>> pyisbn.convert(Permutation_City)
     '9781857982183'
-    >>> print("ISBN %s" % Permutation_City)
-    ISBN 1-85798-218-5
 
-or to process ISBNs using the object pattern use::
+or using the object pattern use::
 
     >>> Permutation_City = pyisbn.Isbn10("1-85798-218-5")
     >>> Permutation_City.validate()
@@ -62,11 +61,8 @@ All independent functions and classes contain (hopefully) useful docstrings.
 API Stability
 -------------
 
-API stability isn't guaranteed across versions, although frivolous changes won't
-be made.
-
-When ``pyisbn`` 1.0 is released the API will be frozen, and any changes which
-aren't backwards compatible will force a major version bump.
+Now that ``pyisbn`` 1.0 has been released the API will is frozen, and any
+changes which aren't backwards compatible will force a major version bump.
 
 Contributors
 ------------
@@ -94,14 +90,14 @@ Ideas
 
 * Kevin Simmons
 
-If I've forgotten to include your name I wholeheartedly apologise.  Just drop me
-a mail_ and I'll update the list!
+If I've forgotten to include your name I wholeheartedly apologise.  Just drop
+me a mail_ and I'll update the list!
 
 Bugs
 ----
 
-If you find any problems, bugs or just have a question about this package either
-file an issue_ or drop me a mail_.
+If you find any problems, bugs or just have a question about this package
+either file an issue_ or drop me a mail_.
 
 If you've found a bug please attempt to include a minimal testcase so I can
 reproduce the problem, or even better a patch!
@@ -111,3 +107,7 @@ reproduce the problem, or even better a patch!
 .. _Python: http://www.python.org/
 .. _issue: https://github.com/JNRowe/pyisbn/issues
 .. _mail: jnrowe@gmail.com
+
+.. |ISBNs| raw:: html
+
+   <abbr title="International Standard Book Numbers">ISBN</abbr>s

doc/api/isbn.rst

@@ -3,8 +3,9 @@
 Handling ISBNs
 ==============
 
-The :py:class:`Isbn` supports SBNs, ISBN-10 and -13.  If you're handling
-multiple inputs it is easiest to use this class.
+The :class:`Isbn` supports :abbr:`SBNs (Standard Book Numbering)`, :abbr:`ISBN
+(International Standard Book Number)`-10 and -13.  If you're handling multiple
+inputs it is easiest to use this class.
 
 .. autoclass:: Isbn
 

doc/conf.py

@@ -1,21 +1,21 @@
 #
 # coding=utf-8
-"""conf - Sphinx configuration information"""
-# Copyright © 2007-2017  James Rowe <jnrowe@gmail.com>
+"""conf - Sphinx configuration information."""
+# Copyright © 2011-2017  James Rowe <jnrowe@gmail.com>
 #
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
+# This file is part of pyisbn.
 #
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# pyisbn is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
 #
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# pyisbn is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 #
+# You should have received a copy of the GNU General Public License along with
+# pyisbn.  If not, see <http://www.gnu.org/licenses/>.
 
 import os
 import sys
@@ -38,15 +38,15 @@ def check_output(cmd):
 root_dir = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
 sys.path.insert(0, root_dir)
 
-import pyisbn
+import pyisbn  # NOQA
 
 extensions = \
     ['sphinx.ext.%s' % ext for ext in ['autodoc', 'coverage', 'doctest',
-                                       'ifconfig', 'intersphinx', 'napoleon',
-                                       'todo', 'viewcode']] \
-    + ["sphinxcontrib.%s" % ext for ext in ['cheeseshop']]
+                                       'extlinks', 'ifconfig', 'intersphinx',
+                                       'napoleon', 'todo', 'viewcode']] \
+    + ['sphinxcontrib.%s' % ext for ext in []]
 
-# Only activate spelling, if it is installed.  It is not required in the
+# Only activate spelling if it is installed.  It is not required in the
 # general case and we don't have the granularity to describe this in a clean
 # way
 try:
@@ -66,7 +66,7 @@ def check_output(cmd):
 except NameError:
     copyright = pyisbn.__copyright__
 
-version = ".".join(map(str, pyisbn._version.tuple[:2]))
+version = '.'.join(map(str, pyisbn._version.tuple[:2]))
 release = pyisbn._version.dotted
 
 pygments_style = 'sphinx'
@@ -78,12 +78,24 @@ def check_output(cmd):
     pass
 
 # Autodoc extension settings
-autoclass_content = "init"
+autoclass_content = 'init'
+autodoc_default_flags = ['members', ]
 
+# intersphinx extension settings
 intersphinx_mapping = {
-    'python': ('http://docs.python.org/', os.getenv('SPHINX_PYTHON_OBJECTS')),
+    k: (v, os.getenv('SPHINX_%s_OBJECTS' % k.upper()))
+    for k, v in {
+        'python': 'http://docs.python.org/',
+    }.items()
 }
 
+# extlinks extension settings
+extlinks = {
+    'pypi': ('http://pypi.python.org/pypi/%s', ''),
+    'issue': ('https://github.com/JNRowe/jnrbase/issues/%s', 'GitHub #'),
+}
+
+# spelling extension settings
 spelling_lang = 'en_GB'
 spelling_word_list_filename = 'wordlist.txt'
 

doc/faq.rst

@@ -2,7 +2,6 @@ Frequently Asked Questions
 --------------------------
 
 ..
-
    Sadly, these two questions come up often enough that I've felt the need to
    write a pre-emptive response here.  I hoping it will allow me to skip the
    awkwardness I feel when writing individual replies...

doc/fun.rst

@@ -1,16 +1,18 @@
 Fun and games
 -------------
 
-With ISBN-13 a book can have a valid checksum and have a simple transcription
-error, if digits with a difference of five are transposed.
+With :abbr:`ISBN (International Standard Book Number)`-13 a book can have
+a valid checksum and have a simple transcription error, if digits with
+a difference of five are transposed.
 
 Using "The Statistical Mechanics of Financial Markets" as an example, we can see
 that 9783540009788 is the `given ISBN`_, and is valid.  However,
 9738540009788 with the third and fourth characters transposed is also valid, yet
-is incorrect[1]_ .
+is incorrect [1]_.
 
 I'll leave it as an exercise for the reader to figure out how often books with
-transposable ISBN-13s occur in a given library of ``n`` books.
+transposable :abbr:`ISBN (International Standard Book Number)`-13 occur in
+a given library of ``n`` books.
 
 .. [1] This example was chosen to show that sometimes it is still possible to
        catch during data entry as 973 isn't a valid prefix

doc/index.rst

@@ -7,8 +7,8 @@
 
 :mod:`pyisbn` is a `GPL v3`_ licensed module for working with various book
 identification numbers.  It includes functions for conversion, verification and
-generation of checksums.  It also includes basic classes for representing ISBNs
-as objects.
+generation of checksums.  It also includes basic classes for representing
+:abbr:`ISBNs (International Standard Book Numbers)` as objects.
 
 :Git repository:  https://github.com/JNRowe/pyisbn/
 :Issue tracker:  https://github.com/JNRowe/pyisbn/issues/

doc/install.rst

@@ -1,3 +1,5 @@
+.. highlight:: console
+
 Installation
 ------------
 

doc/release.rst

@@ -1,7 +1,7 @@
 Release HOWTO
 =============
 
-.. highlight:: sh
+.. highlight:: console
 
 ..
   Much of this stuff is automated locally, but I'm describing the process for
@@ -12,9 +12,9 @@ Release HOWTO
 Test
 ----
 
-In the general case tests can be run via ``nose2``::
+In the general case tests can be run via :pypi:`nose2`::
 
-    $ nose2 -vv tests
+    $ nose2 tests
 
 When preparing a release it is important to check that :mod:`pyisbn` works with
 all currently supported Python versions, and that the documentation is correct.
@@ -34,8 +34,8 @@ Update PyPI
 -----------
 
 ..
-  This is the section you're especially likely to get wrong at some point if you
-  try to handle all of this manually ;)
+  This is the section you're especially likely to get wrong at some point if
+  you try to handle all of this manually ;)
 
 Create and upload the new release tarballs to PyPI::
 

extra/_pyisbn

@@ -1,21 +1,21 @@
 #compdef pyisbn pyisbn.py
 # coding=utf-8
 # pyisbn - ZSH completion support for pyisbn
-# Copyright © 2007-2017  James Rowe <jnrowe@gmail.com>
+# Copyright © 2012-2017  James Rowe <jnrowe@gmail.com>
 #
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
+# This file is part of pyisbn.
 #
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# pyisbn is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
 #
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# pyisbn is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 #
+# You should have received a copy of the GNU General Public License along with
+# pyisbn.  If not, see <http://www.gnu.org/licenses/>.
 
 # Most of this file is generated from pyisbn/tool.py, but feel free to
 # customise it!  If you make improvements, open a pull request against

extra/tool.py

@@ -1,21 +1,21 @@
 #! /usr/bin/env python
 # coding=utf-8
-"""tool - A simple pyisbn interface for the command line"""
-# Copyright © 2007-2017  James Rowe <jnrowe@gmail.com>
+"""tool - A simple pyisbn interface for the command line."""
+# Copyright © 2013-2017  James Rowe <jnrowe@gmail.com>
 #
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
+# This file is part of pyisbn.
 #
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# pyisbn is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
 #
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# pyisbn is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 #
+# You should have received a copy of the GNU General Public License along with
+# pyisbn.  If not, see <http://www.gnu.org/licenses/>.
 
 # You won't find this pretty… however it was quick to write and it's compatible
 # with 2.4-3.3