Metadata-Version: 1.1
Name: doq
Version: 0.9.0
Summary: Docstring generator
Home-page: http://github.com/heavenshell/py-doq
Author: Shinya Ohyanagi
Author-email: sohyanagi@gmail.com
License: BSD
Description: doq
        ---
        
        .. image:: https://github.com/heavenshell/py-doq/workflows/build/badge.svg
            :target: https://github.com/heavenshell/py-doq/actions
        
        .. image:: https://pyup.io/repos/github/heavenshell/py-doq/python-3-shield.svg
            :target: https://pyup.io/repos/github/heavenshell/py-doq/
            :alt: Python 3
        
        .. image:: https://pyup.io/repos/github/heavenshell/py-doq/shield.svg
            :target: https://pyup.io/repos/github/heavenshell/py-doq/
            :alt: Updates
        
        Docstring generator.
        
        Installation
        ============
        
        .. code::
        
          $ pip install doq
        
        How to use
        ==========
        
        .. code::
        
          $ cat spam.py
          def spam(arg1, arg2: str) -> str:
              pass
        
        .. code::
        
          $ cat spam.py | doq
          def spam(arg1, arg2: str) -> str:
            """spam.
        
            :param arg1:
            :param arg2:
            :type arg2: str
            :rtype: str
            """
            pass
        
        Default formatter is `sphinx`. You can choose `sphinx`, `google` or `numpy`.
        
        .. code::
        
          $ cat spam.py | doq --formatter=google
          def spam(arg1, arg2: str) -> str:
            """spam.
        
            Args:
                arg1 : arg1
                arg2 (str): arg2
        
            Returns:
                str:
            """
            pass
        
        .. code::
        
          $ cat spam.py | doq --formatter=numpy
          def spam(arg1, arg2: str) -> str:
            """spam.
        
            Parameters
            ----------
            arg1
                  arg1
            arg2 : str
                 arg2
        
            Returns
            -------
            str
        
            """
            pass
        
        Usage
        =====
        
        .. code::
        
            $ python -m doq.cli --help
            usage: doq [-h] [-f FILE] [--start START] [--end END] [-t TEMPLATE_PATH]
                       [-s STYLE] [--formatter FORMATTER] [--indent INDENT] [--omit OMIT]
                       [-r] [-d DIRECTORY] [-w] [-v] [-c CONFIG] [--ignore_exception]
                       [--ignore_yield] [--ignore_init]
        
            Docstring generator.
        
            optional arguments:
              -h, --help            show this help message and exit
              -f FILE, --file FILE  File or STDIN
              --start START         Start lineno
              --end END             End lineno
              -t TEMPLATE_PATH, --template_path TEMPLATE_PATH
                                    Path to template directory
              -s STYLE, --style STYLE
                                    Output style string or json
              --formatter FORMATTER
                                    Docstring formatter. sphinx,google or numpy
              --indent INDENT       Indent number
              --omit OMIT           Omit first argument such as self
              -r, --recursive       Run recursively over directories
              -d DIRECTORY, --directory DIRECTORY
                                    Path to directory
              -w, --write           Edit files in-place
              -v, --version         Output the version number
              -c CONFIG, --config CONFIG
                                    Path to a setup.cfg or pyproject.toml
              --ignore_exception    Ignore exception statements
              --ignore_yield        Ignore yield statements
              --ignore_init         Ignore generate docstring to __init__ method
        
        Customize template
        ==================
        
        doq use Jinja2 template. So you can create your own template.
        
        .. note::
        
            You must create 3 template files.
        
        +-----------+-----------------------------------------+
        | File name | Description                             |
        +===========+=========================================+
        | class.txt | class docstring                         |
        +-----------+-----------------------------------------+
        | def.txt   | def / method docstring                  |
        +-----------+-----------------------------------------+
        | noarg.txt | def / method without argument docstring |
        +-----------+-----------------------------------------+
        
        Available Jinja2's variable
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        +--------------------------+---------------------------+
        | Name                     | Description               |
        +==========================+===========================+
        | name                     | class, method, def's name |
        +-------------+------------+---------------------------+
        | params      | argument   | Method, def's argument    |
        |             +------------+---------------------------+
        |             | annotation | Argument's type hint      |
        |             +------------+---------------------------+
        |             | default    | Defaut keyword argument   |
        +-------------+------------+---------------------------+
        | exceptions               | List of exception         |
        +--------------------------+---------------------------+
        | yields                   | List of yield             |
        +--------------------------+---------------------------+
        | return_type              | Return type hint          |
        +--------------------------+---------------------------+
        
        See `examples <https://github.com/heavenshell/py-doq/tree/master/examples>`_
        
        Configuration
        =============
        
        doq will automatically search ``setup.cfg`` or ``pyproject.toml`` in your
        project.
        
        .. note::
        
            ignore_exception, ignore_exception and ignore_init can set `true` only.
            If you want turn off, remove from configuration.
        
        setup.cfg
        ~~~~~~~~~
        
        The section must be ``[doq]``.
        
        configuration file example::
        
          [doq]
          style = "json"
          template_path = "/path/to/template"
        
        pyproject.toml
        ~~~~~~~~~~~~~~
        
        The section must be ``[tool.doq]``.
        
        configuration file example::
        
          [tool.doq]
          style = "json"
          template_path = "/path/to/template"
        
        LICENSE
        =======
        
        NEW BSD LICENSE.
        
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
