Documentation utility functions
===============================

.. :doctest:

We're testing ``preparedocs.py`` here:

    >>> from zest.releaser import preparedocs


Entry-point-documentation-generation entry point
------------------------------------------------

The entry point for generating documentation does not run when the project
name isn't zest.releaser.  Otherwise we would generate our documentation every
time we used zest.releaser...

    >>> data = {'name': 'vanrees.worlddomination'}
    >>> preparedocs.prepare_entrypoint_documentation(data) is None
    True

Prepare a mock documentation file:

    >>> import os
    >>> import shutil
    >>> import tempfile
    >>> tempdir = tempfile.mkdtemp()
    >>> mock_docdir = os.path.join(tempdir, 'doc', 'source')
    >>> os.makedirs(mock_docdir)
    >>> docfile = os.path.join(mock_docdir, 'entrypoints.rst')
    >>> with open(docfile, 'w') as f:
    ...     _ = f.write("""
    ... line1
    ... line2
    ... .. ### AUTOGENERATED FROM HERE ###
    ... line3
    ... """)

When the name *is* zest.releaser, we generate documentation.

    >>> data = {'name': 'zest.releaser',
    ...         'reporoot': tempdir}
    >>> preparedocs.prepare_entrypoint_documentation(data)
    Wrote entry point documentation to ...doc/source/entrypoints.rst

The lines above the marker interface are still intact, the line below it has
been replaced by the generated documentation:

    >>> with open(docfile) as f:
    ...     print(f.read())
    <BLANKLINE>
    line1
    line2
    .. ### AUTOGENERATED FROM HERE ###
    <BLANKLINE>
    Common data dict items
    ----------------------
    <BLANKLINE>
    These items are shared among all commands.
    <BLANKLINE>
    commit_msg
        Message template used when committing
    ...
    ``prerelease`` data dict items
    ------------------------------
    ...

Clean up

    >>> shutil.rmtree(tempdir)
