Metadata-Version: 1.2
Name: py2annotate
Version: 1.1.0
Summary: An extension to Sphinx :code:`autodoc` to augment Sphinx documentation with type annotations, when using Python 2 style type annotations.
Home-page: https://github.com/patrick-kidger/py2annotate
Author: Patrick Kidger
Author-email: contact@kidger.site
Maintainer: Patrick Kidger
Maintainer-email: contact@kidger.site
License: Apache-2.0
Description: ***********
        py2annotate
        ***********
        An extension to Sphinx :code:`autodoc` to augment Sphinx documentation with type annotations, when using Python 2 style type annotations.
        
        The Problem
        ===========
        Python 2 doesn't support type annotations. Thus writing Python 2 / Python 3 agnostic code with type annotations requires `putting the type annotations in comments <https://mypy.readthedocs.io/en/latest/python2.html>`__:
        
        .. code-block:: python
        
            def add(x, y):
                # type: (int, int) -> int
                """Adds two numbers."""
                return x + y
        
        But now when documentation is generated with `Sphinx <http://www.sphinx-doc.org/en/master/>`__, the documentation doesn't include type annotations:
        
        .. image:: https://raw.githubusercontent.com/patrick-kidger/py2annotate/master/imgs/without-annotations.png
            :align: center
        
        
        *Example from the* |signatory|_ *project.*
        
        .. _signatory: https://github.com/patrick-kidger/signatory
        .. |signatory| replace:: *Signatory*
        
        The Solution
        ============
        
        This extension remedies things so that the Sphinx documentation now looks like:
        
        .. image:: https://raw.githubusercontent.com/patrick-kidger/py2annotate/master/imgs/with-annotations.png
            :align: center
        
        .. role:: python(code)
            :language: python
        
        (which is the same as what you'd get using Python 3 style type annotations e.g. :python:`def add(x: int, y: int) -> int`)
        
        Installation
        ============
        Via pip:
        
        .. code-block:: bash
        
            pip install py2annotate
        
        It's also just a single file, so copy-paste the code if you want.
        
        Requires Python 3.6+.
        
        Usage
        =====
        Just add py2annotate to the list of extensions in :code:`conf.py`:
        
        .. code-block:: python
        
            # conf.py
            ...
            extensions = ['sphinx.ext.autodoc', 'py2annotate']
            ...
        
        (It shouldn't matter whether it comes before or after :code:`autodoc`.)
        
        Note that Sphinx itself must be run using Python 3.6+. This is because py2annotate uses the Python 3 style type
        annotations internally in order to determine the correct annotations.
        
        Known Issues
        ============
        None so far! File a report if you run into anything. `mypy <https://mypy.readthedocs.io/en/latest/index.html>`__ and `stubgen <https://mypy.readthedocs.io/en/latest/stubgen.html>`__ are used internally though, so your code's formatting must be in a manner that they understand.
Keywords: signature
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.6
