pygenstub
=========

pygenstub is a utility for generating stub files from docstrings
in source files.

If the docstring of a function includes a **sig** field,
the value of that field will be used to generate a stub
by matching the types to the parameters in the same order.

For example, for the function given below:

.. code-block:: python

   def foo(a, b):
       """Do foo.

       :sig: (int, str) -> None
       """

pygenstub will generate the following stub:

.. code-block:: python

   def foo(a: int, b: str) -> None: ...

pygenstub consists of a single `source file`_ which contains such signatures.
You can check the `stub file`_ generated by running pygenstub on itself
as an example.

Getting started
---------------

pygenstub runs on Python 3.6 and later versions.
You can install the latest version from `PyPI`_::

  pip install pygenstub

Installation creates a script named ``pygenstub`` which can be used
as follows::

  pygenstub foo.py

This command will generate the file ``foo.pyi`` in the same directory
as the input file.
If the output file already exists, it will be overwritten.

If you download the `source file`_, you can also run it directly
without installing::

  python pygenstub.py foo.py

If pygenstub is activated as a Sphinx extension (after *sphinx.ext.autodoc*),
it will insert type comments into the docstring:

.. code-block:: python

   extensions = [
       "sphinx.ext.autodoc",
       "pygenstub"
   ]

As an example of the output, you can check the `API documentation`_
for pygenstub itself.

Getting help
------------

The documentation is available on: https://pygenstub.readthedocs.io/

The source code can be obtained from: https://github.com/uyar/pygenstub

License
-------

Copyright (C) 2016-2021 H. Turgut Uyar <uyar@tekir.org>

pygenstub is released under the GPL license, version 3 or later.
Read the included `LICENSE.txt`_ for details.

.. _PyPI: https://pypi.org/project/pygenstub/
.. _source file: https://github.com/uyar/pygenstub/blob/master/pygenstub.py
.. _stub file: https://github.com/uyar/pygenstub/blob/master/pygenstub.pyi
.. _API documentation: https://pygenstub.readthedocs.io/en/latest/api.html
.. _LICENSE.txt: https://github.com/uyar/pygenstub/blob/master/LICENSE.txt
