new: doc: add basic sphinx docs build using apidoc, update changelog

* update .gitignore and .gitchangelog.rc and (re)generate new changelog
* add sphinx docs build using apidoc extension and readme/changelog
  symlinks
* rst apidoc modules are auto-generated and are in .gitignore
  along with the generated html dir
* add dependencies to packaging and add docs/changes cmds to tox file.
  Includes a tox extension for shared tox environments; the new tox
  commands are an example of this => 4 cmds using one tox env

Signed-off-by: Stephen Arnold <[email protected]>

.gitchangelog.rc

@@ -64,6 +64,7 @@ ignore_regexps = [
     r'@wip', r'!wip',
     r'^([cC]hg|[fF]ix|[nN]ew)\s*:\s*[p|P]kg:',
     r'^([cC]hg|[fF]ix|[nN]ew)\s*:\s*[d|D]ev:',
+    r'^([cC]i)\s*:',
     r'^(.{3,3}\s*:)?\s*[fF]irst commit.?\s*$',
     r'^$',  ## ignore commits with empty messages
 ]
@@ -85,16 +86,17 @@ section_regexps = [
     ('New', [
         r'^[nN]ew\s*:\s*((dev|use?r|pkg|test|doc)\s*:\s*)?([^\n]*)$',
      ]),
+    ('Features', [
+       r'^([nN]ew|[fF]eat)\s*:\s*((dev|use?r|pkg|test|doc)\s*:\s*)?([^\n]*)$',
+     ]),
     ('Changes', [
         r'^[cC]hg\s*:\s*((dev|use?r|pkg|test|doc)\s*:\s*)?([^\n]*)$',
      ]),
-    ('Fix', [
+    ('Fixes', [
         r'^[fF]ix\s*:\s*((dev|use?r|pkg|test|doc)\s*:\s*)?([^\n]*)$',
      ]),
-
     ('Other', None ## Match all lines
      ),
-
 ]
 
 
@@ -150,7 +152,9 @@ subject_process = (strip |
 ##
 ## Tags that will be used for the changelog must match this regexp.
 ##
-tag_filter_regexp = r'^[0-9]+\.[0-9]+(\.[0-9]+)?$'
+#tag_filter_regexp = r'^v?[0-9]+\.[0-9]+(\.[0-9]+)?$'
+#tag_filter_regexp = r'^[0-9]+\.[0-9]+(\.[0-9]+)?$'
+tag_filter_regexp = r'.*?$'  # accept funky tag strings
 
 
 ## ``unreleased_version_label`` is a string or a callable that outputs a string
@@ -160,7 +164,9 @@ tag_filter_regexp = r'^[0-9]+\.[0-9]+(\.[0-9]+)?$'
 #unreleased_version_label = "(unreleased)"
 unreleased_version_label = lambda: swrap(
     ["git", "describe", "--tags"],
-shell=False)
+    shell=False,
+)
+
 
 ## ``output_engine`` is a callable
 ##
@@ -227,7 +233,7 @@ include_merge = True
 ##        Outputs directly to standard output
 ##        (This is the default)
 ##
-##   - FileInsertAtFirstRegexMatch(file, pattern, idx=lamda m: m.start())
+##   - FileInsertAtFirstRegexMatch(file, pattern, idx=lamda m: m.start(), flags)
 ##
 ##        Creates a callable that will parse given file for the given
 ##        regex pattern and will insert the output in the file.
@@ -242,7 +248,7 @@ include_merge = True
 ##        take care of everything and might be more complex. Check the README
 ##        for a complete copy-pastable example.
 ##
-# publish = FileInsertIntoFirstRegexMatch(
+# publish = FileInsertAtFirstRegexMatch(
 #     "CHANGELOG.rst",
 #     r'/(?P<rev>[0-9]+\.[0-9]+(\.[0-9]+)?)\s+\([0-9]+-[0-9]{2}-[0-9]{2}\)\n--+\n/',
 #     idx=lambda m: m.start(1)

.gitignore

@@ -8,7 +8,54 @@ src/*.html
 tests/*.so
 tests/access.log
 *~
-*.so
 *.pyc
 *.swp
 *.egg-info
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Sphinx documentation
+docs/_build/
+docs/source/api/
+