Metadata-Version: 2.0
Name: marrydoc
Version: 0.1.0
Summary: Easy docstring maintenance.
Home-page: https://gitlab.com/dangass/marrydoc
Author: Dan Gass
Author-email: dan.gass@gmail.com
Maintainer: Dan Gass
Maintainer-email: dan.gass@gmail.com
License: MIT License ; http://opensource.org/licenses/MIT
Download-URL: https://gitlab.com/dangass/marrydoc
Keywords: docstring
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Text Processing
Requires-Python: >=2.7.0,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
Provides-Extra: test
Provides-Extra: doc
Requires-Dist: setuptools (>=39.0.1)
Requires-Dist: enum34 (>=1.1.6); python_version < "3.0"
Provides-Extra: doc
Requires-Dist: Sphinx (>=1.6.7); extra == 'doc'
Requires-Dist: sphinx-rtd-theme; extra == 'doc'
Requires-Dist: sphinxcontrib-programoutput; extra == 'doc'
Provides-Extra: test
Requires-Dist: baseline; extra == 'test'
Requires-Dist: nose; extra == 'test'
Provides-Extra: test
Requires-Dist: mock (>=2.0.0); python_version < "3.0" and extra == 'test'
Requires-Dist: unittest2; python_version < "3.0" and extra == 'test'

#####################################
[MarryDoc] Easy DocString Maintenance
#####################################

.. currentmodule:: marrydoc

.. image:: https://readthedocs.org/projects/marrydoc/badge/?version=latest
    :target: https://marrydoc.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

The :mod:`marrydoc` Python module makes maintaining consistency of
related Python docstrings easy. :mod:`marrydoc` provides decorators to
"wed" a docstring to another and provides a command line tool to
automatically update a module's docstrings when their basis docstrings
have changed.

The decorators offered annotate class, function, and method docstrings to
identify if their docstring is to be inherited from, maintained as a copy
of, or maintained as a modified copy of a docstring of another program
construct.


***********
Quick Start
***********

@inherit
========

Use the :func:`inherit()` decorator to dynamically copy a docstring from
one program construct to another when a module is imported. For example:

.. code-block:: python

    import marrydoc
    from foo import bar

    @marrydoc.inherit(bar)
    def my_bar():
        pass

    assert bar.__doc__ == my_bar.__doc__


@copied_from
============

Use the :func:`copied_from` decorator in combination with the command line
tool to evaluate if one program construct docstring is up to date with
another and automatically update the script if they are unequal. For
example:

.. code-block:: python

    import marrydoc
    from foo import bar

    @marrydoc.copied_from(bar)
    def my_bar():
        """Perform foo bar."""
        pass


Then use the command line tool to evaluate if the source docstring has
changed and automatically update if so:

.. code-block:: shell

    $ python -m marrydoc --merge my_foo.py
    my_foo.py ... OK


@based_on
=========

Use the :func:`based_on` decorator instead of :func:`copied_from`
when the docstring is a copy but has been modified. Pass an unmodified
copy of the source docstring as the second argument to :func:`based_on`
(to facilitate source docstring change detection and provide a basis of
a three way merge). For example:

.. code-block:: python

    import marrydoc
    from foo import bar

    @marrydoc.based_on(
        bar,
        """Perform foo bar.""")
    def my_bar():
        """Perform my special foo bar."""
        pass


Then use the command line tool to evaluate if the source docstring has
changed and automatically perform a three way merge if so:

.. code-block:: shell

    $ python -m marrydoc --merge my_foo.py
    my_foo.py ... UPDATED


