Fix reference in docs and some minor project issues.

.cookiecutterrc

@@ -1,55 +1,52 @@
 # Generated by cookiepatcher, a small shim around cookiecutter (pip install cookiepatcher)
 
 cookiecutter:
-    _extensions:
-    -   jinja2_time.TimeExtension
-    _template: /home/ionel/open-source/cookiecutter-pylibrary
-    allow_tests_inside_package: no
-    appveyor: yes
-    c_extension_function: '-'
-    c_extension_module: '-'
-    c_extension_optional: no
+    full_name: Ionel Cristian Mărieș
+    email: contact@ionelmc.ro
+    website: https://blog.ionelmc.ro/
+    project_name: tblib
+    repo_name: python-tblib
+    repo_hosting: github.com
+    repo_hosting_domain: github.com
+    repo_username: ionelmc
+    package_name: tblib
+    distribution_name: tblib
+    project_short_description: Traceback serialization library.
+    release_date: '2020-03-07'
+    year_from: '2013'
+    year_to: '2'
+    version: 1.6.0
+    license: BSD 2-Clause License
     c_extension_support: no
+    c_extension_optional: no
+    c_extension_module: '-'
+    c_extension_function: '-'
     c_extension_test_pypi: no
     c_extension_test_pypi_username: '-'
-    codacy: no
-    codacy_projectid: '-'
-    codeclimate: no
-    codecov: yes
+    test_matrix_configurator: no
+    test_matrix_separate_coverage: no
+    test_runner: pytest
+    setup_py_uses_test_runner: no
+    setup_py_uses_setuptools_scm: no
+    pypi_badge: yes
+    pypi_disable_upload: no
+    allow_tests_inside_package: no
+    linter: flake8
     command_line_interface: no
     command_line_interface_bin_name: '-'
     coveralls: no
     coveralls_token: '-'
-    distribution_name: tblib
-    email: contact@ionelmc.ro
-    full_name: Ionel Cristian Mărieș
+    codecov: yes
     landscape: no
-    license: BSD 2-Clause License
-    linter: flake8
-    package_name: tblib
-    project_name: tblib
-    project_short_description: Traceback serialization library.
-    pypi_badge: yes
-    pypi_disable_upload: no
-    release_date: '2019-05-02'
-    repo_hosting: github.com
-    repo_hosting_domain: github.com
-    repo_name: python-tblib
-    repo_username: ionelmc
-    requiresio: yes
     scrutinizer: no
-    setup_py_uses_setuptools_scm: no
-    setup_py_uses_test_runner: no
+    codacy: no
+    codacy_projectid: '-'
+    codeclimate: no
     sphinx_docs: yes
-    sphinx_docs_hosting: https://python-tblib.readthedocs.io/
-    sphinx_doctest: no
     sphinx_theme: sphinx-py3doc-enhanced-theme
-    test_matrix_configurator: no
-    test_matrix_separate_coverage: no
-    test_runner: pytest
+    sphinx_doctest: no
+    sphinx_docs_hosting: https://python-tblib.readthedocs.io/
     travis: yes
     travis_osx: no
-    version: 1.4.0
-    website: https://blog.ionelmc.ro/
-    year_from: '2013'
-    year_to: '2019'
+    appveyor: yes
+    requiresio: yes

.readthedocs.yml

@@ -0,0 +1,26 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: docs/requirements.txt
+    # Install package using pip for the build (needed for autodoc)
+    - method: pip
+        path: .

CHANGELOG.rst

@@ -19,7 +19,7 @@ Changelog
 ~~~~~~~~~~~~~~~~~~
 
 * Added support for Python 3.8. Contributed by Victor Stinner in
-  `#42 <HTTPS://GITHUB.COM/IONELMC/PYTHON-TBLIB/ISSUES/42>`_.
+  `#42 <https://github.com/ionelmc/python-tblib/issues/42>`_.
 * Removed support for end of life Python 3.4.
 * Few CI improvements and fixes.
 

LICENSE

@@ -1,7 +1,6 @@
 BSD 2-Clause License
 
-Copyright (c) 2013-2019, Ionel Cristian Mărieș
-All rights reserved.
+Copyright (c) 2013-2020, Ionel Cristian Mărieș. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
 following conditions are met:

MANIFEST.in

@@ -14,6 +14,6 @@ include CONTRIBUTING.rst
 include LICENSE
 include README.rst
 
-include tox.ini .travis.yml .appveyor.yml
+include tox.ini .travis.yml .appveyor.yml .readthedocs.yml
 
-global-exclude *.py[cod] __pycache__ *.so *.dylib
+global-exclude *.py[cod] __pycache__/* *.so *.dylib

README.rst

@@ -15,7 +15,8 @@ Overview
     * - package
       - | |version| |wheel| |supported-versions| |supported-implementations|
         | |commits-since|
-.. |docs| image:: https://readthedocs.org/projects/python-tblib/badge/?style=flat
+
+.. |docs| image:: https://codecov.io/gh/ionelmc/python-tblib/branch/master/graphs/badge.svg?branch=master
     :target: https://readthedocs.org/projects/python-tblib
     :alt: Documentation Status
 

ci/requirements.txt

@@ -1,3 +1,4 @@
 virtualenv>=16.6.0
 pip>=19.1.1
 setuptools>=18.0.1
+six>=1.12.0

docs/conf.py

@@ -4,8 +4,7 @@
 import os
 
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
+    'autoapi.extension',
     'sphinx.ext.coverage',
     'sphinx.ext.doctest',
     'sphinx.ext.extlinks',
@@ -14,10 +13,13 @@
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
 ]
+autoapi_type = 'python'
+autoapi_dirs = ['../src']
+
 source_suffix = '.rst'
 master_doc = 'index'
 project = 'tblib'
-year = '2013-2019'
+year = '2013-2020'
 author = 'Ionel Cristian Mărieș'
 copyright = '{0}, {1}'.format(year, author)
 version = release = '1.6.0'

docs/index.rst

@@ -8,7 +8,6 @@ Contents
    readme
    installation
    usage
-   reference/index
    contributing
    authors
    changelog

docs/requirements.txt

@@ -1,2 +1,3 @@
 sphinx>=1.3
 sphinx-py3doc-enhanced-theme
+sphinx-autoapi

setup.cfg

@@ -6,7 +6,10 @@ max-line-length = 140
 exclude = */migrations/*
 
 [tool:pytest]
-testpaths = tests
+# If a pytest section is found in one of the possible config files
+# (pytest.ini, tox.ini or setup.cfg), then pytest will not look for any others,
+# so if you add a pytest config section elsewhere,
+# you will need to delete this section from setup.cfg.
 norecursedirs =
     migrations
 
@@ -23,6 +26,8 @@ addopts =
     --doctest-continue-on-failure
     --doctest-glob=\*.rst
     --tb=short
+testpaths =
+    tests
 
 [tool:isort]
 force_single_line = True

src/tblib/__init__.py

@@ -17,7 +17,7 @@
     raise ImportError("Cannot use tblib. Runtime not supported.")
 
 __version__ = '1.6.0'
-__all__ = 'Traceback',
+__all__ = 'Traceback', 'TracebackParseError', 'Frame', 'Code'
 
 PY3 = sys.version_info[0] == 3
 FRAME_RE = re.compile(r'^\s*File "(?P<co_filename>.+)", line (?P<tb_lineno>\d+)(, in (?P<co_name>.+))?$')
@@ -43,6 +43,9 @@ class TracebackParseError(Exception):
 
 
 class Code(object):
+    """
+    Class that replicates just enough of the builtin Code object to enable serialization and traceback rendering.
+    """
     co_code = None
 
     def __init__(self, code):
@@ -61,13 +64,19 @@ def __reduce__(self):
 
     # noinspection SpellCheckingInspection
     def __tproxy__(self, operation, *args, **kwargs):
+        """
+        Necessary for PyPy's tproxy.
+        """
         if operation in ('__getattribute__', '__getattr__'):
             return getattr(self, args[0])
         else:
             return getattr(self, operation)(*args, **kwargs)
 
 
 class Frame(object):
+    """
+    Class that replicates just enough of the builtin Frame object to enable serialization and traceback rendering.
+    """
     def __init__(self, frame):
         self.f_locals = {}
         self.f_globals = {
@@ -79,14 +88,18 @@ def __init__(self, frame):
         self.f_lineno = frame.f_lineno
 
     def clear(self):
-        # For compatibility with PyPy 3.5;
-        # clear() was added to frame in Python 3.4
-        # and is called by traceback.clear_frames(), which
-        # in turn is called by unittest.TestCase.assertRaises
-        pass
+        """
+        For compatibility with PyPy 3.5;
+        clear() was added to frame in Python 3.4
+        and is called by traceback.clear_frames(), which
+        in turn is called by unittest.TestCase.assertRaises
+        """
 
     # noinspection SpellCheckingInspection
     def __tproxy__(self, operation, *args, **kwargs):
+        """
+        Necessary for PyPy's tproxy.
+        """
         if operation in ('__getattribute__', '__getattr__'):
             if args[0] == 'f_code':
                 return tproxy(CodeType, self.f_code.__tproxy__)
@@ -97,6 +110,9 @@ def __tproxy__(self, operation, *args, **kwargs):
 
 
 class Traceback(object):
+    """
+    Class that wraps builtin Traceback objects.
+    """
     tb_next = None
 
     def __init__(self, tb):
@@ -117,6 +133,9 @@ def __init__(self, tb):
             tb = tb.tb_next
 
     def as_traceback(self):
+        """
+        Convert to a builtin Traceback object that is usable for raising or rendering a stacktrace.
+        """
         if tproxy:
             return tproxy(TracebackType, self.__tproxy__)
         if not tb_set_next:
@@ -172,6 +191,9 @@ def as_traceback(self):
 
     # noinspection SpellCheckingInspection
     def __tproxy__(self, operation, *args, **kwargs):
+        """
+        Necessary for PyPy's tproxy.
+        """
         if operation in ('__getattribute__', '__getattr__'):
             if args[0] == 'tb_next':
                 return self.tb_next and self.tb_next.as_traceback()
@@ -183,7 +205,10 @@ def __tproxy__(self, operation, *args, **kwargs):
             return getattr(self, operation)(*args, **kwargs)
 
     def as_dict(self):
-        """Convert a Traceback into a dictionary representation"""
+        """
+        Converts to a dictionary representation. You can serialize the result to JSON as it only has
+        builtin objects like dicts, lists, ints or strings.
+        """
         if self.tb_next is None:
             tb_next = None
         else:
@@ -207,6 +232,9 @@ def as_dict(self):
 
     @classmethod
     def from_dict(cls, dct):
+        """
+        Creates an instance from a dictionary with the same structure as ``.as_dict()`` returns.
+        """
         if dct['tb_next']:
             tb_next = cls.from_dict(dct['tb_next'])
         else:
@@ -230,6 +258,10 @@ def from_dict(cls, dct):
 
     @classmethod
     def from_string(cls, string, strict=True):
+        """
+        Creates an instance by parsing a stacktrace. Strict means that parsing stops when lines are not indented by at least two spaces
+        anymore.
+        """
         frames = []
         header = strict
 

tox.ini

@@ -25,10 +25,10 @@ basepython =
     pypy3: {env:TOXPYTHON:pypy3}
     py27: {env:TOXPYTHON:python2.7}
     py35: {env:TOXPYTHON:python3.5}
-    {py36,docs}: {env:TOXPYTHON:python3.6}
+    py36: {env:TOXPYTHON:python3.6}
     py37: {env:TOXPYTHON:python3.7}
     py38: {env:TOXPYTHON:python3.8}
-    {bootstrap,clean,check,report,codecov}: {env:TOXPYTHON:python3}
+    {bootstrap,clean,check,report,codecov,docs}: {env:TOXPYTHON:python3}
 setenv =
     PYTHONPATH={toxinidir}/tests
     PYTHONUNBUFFERED=yes