Metadata-Version: 2.1
Name: argparse-manpage
Version: 4.7
Summary: Build manual page from python's ArgumentParser object.
Home-page: https://github.com/praiskup/argparse-manpage
Author: Gabriele Giammatteo
Author-email: gabriele.giammatteo@eng.it
Maintainer: Pavel Raiskup
Maintainer-email: praiskup@redhat.com
License: Apache-2.0
Description: # ArgumentParser instance → manual page
        
        Avoid documenting your Python script arguments on two places!  This is typically
        done in an [argparse.ArgumentParser][ap-docs] help configuration (`help=`,
        `description=`, etc.), and also in a manually crafted manual page.
        
        The good thing about an `ArgumentParser` objects is that it actually provides
        a traversable "tree-like" structure, with all the necessary info needed to
        **automatically generate** documentation, for example in a *groff* typesetting
        system (manual pages).  And this is where this project can help.
        
        There are two supported ways to generate the manual, either script it using the
        installed command `argparse-manpage`, or via `setup.py build` automation (with a
        slight bonus of automatic manual page installation with `setup.py install`).
        
        
        ## What is need?
        
        Most of the (meta)data is stored in the `ArgumentParser` object, therefore
        `argparse-manpage` needs to know its location—it can be either the object
        itself, or a method to call to get the object [^1].
        
        On top of this, several manual page fields (like *author* or *project* name)
        need to be specified, either on command-line or via `setup.py` metadata.
        
        
        ## Command-line usage
        
        See the following example:
        
        ```
        $ argparse-manpage --pyfile ./pythonfile.py --function get_parser \
                           --author "John --author-email doe@example.com" \
                           --project-name myproject --url https://pagure.io/myproject \
        > cool-manpage.1
        ```
        
        This (a) processes the `./pythonfile.py`, (b) calls the `get_parser` inside to
        obtain the `ArgumentParser` instance, (c) transforms it into a manual page and
        (d) stores it into the `cool-manpage.1` file.
        
        Alternatively those options above can be combined with
        
        - option `--module mymodule.main`, to load a Python module `mymodule.main`
          from `PYTHONPATH`, or
        - `--object parser_object_name` if the `parser_object_name` is a global
          variable.
        
        
        ## Use with pyproject.toml
        
        First, you need to declare in `pyproject.toml` that argparse-manpage is needed
        at build-time and use the setuptools.builds_meta` backend:
        
        ```toml
        [build-system]
        requires = ["argparse-manpage[setuptools]"]
        build-backend = "setuptools.build_meta"
        ```
        
        Alternatively, you can place the `build_manpages` (sub)directory from this
        project somewhere onto `PYTHONPATH` so you can use it at build time.  For
        example:
        
        ```bash
        git submodule add --name build_manpages https://github.com/praiskup/build_manpages
        git submodule update --init
        ```
        
        Then in `pyproject.toml` (re)define `cmdclass` commands:
        
        ```toml
        [tool.setuptools.cmdclass]
        build_py = "build_manpages.build_py"
        install = "build_manpages.install"
        build_manpages = "build_manpages.build_manpages"
        ```
        
        And specify the list of built manual pages:
        
        ```toml
        [tool.build_manpages]
        manpages = [
            "man/foo.1:object=parser:pyfile=bin/foo.py",
            "man/bar.1:function=get_parser:pyfile=bin/bar",
            "man/baz.1:function=get_parser:pyfile=bin/bar:prog=baz",
        ]
        ```
        
        ## Use with setup.py
        
        In your `setup.py` use pattern like:
        
        ```python
        [...]
        from build_manpages import build_manpages, get_build_py_cmd, get_install_cmd
        
        setup(
          [...]
          cmdclass={
              'build_manpages': build_manpages,
              # Re-define build_py and install commands so the manual pages
              # are automatically re-generated and installed
              'build_py': get_build_py_cmd(),
              'install': get_install_cmd(),
          }
        )
        ```
        
        And in `setup.cfg` configure the manual pages you want to automatically
        generate and install:
        
        ```
        [build_manpages]
        manpages =
            man/foo.1:object=parser:pyfile=bin/foo.py
            man/bar.1:function=get_parser:pyfile=bin/bar
            man/baz.1:function=get_parser:pyfile=bin/bar:prog=baz
        ```
        
        ## List of manual pages
        
        The format of those lines is a colon separated list of arguments/options.  The
        first argument determines the filename of the generated manual page.  Then
        follows a list of options of format `option=value`.  Supported values are:
        
        - pyfile - what python file the argparse object resides in
        - object - the name of arparse object in "pyfile" to import
        - function - the name of function in pyfile to call to get the argparse object
        - format - format of the generated man page: `pretty` (default), `single-commands-section`
        - author - author of the program; can be specified multiple times
        - description - description of the program, used in the NAME section, after the
            leading 'name - ' part, see man (7) man-pages for more info
        - project_name - name of the project the program is part of
        - version - version of the project, visible in manual page footer
        - prog - value that substitutes %prog in ArgumentParser's usage
        - url - link to project download page
        - manual_section - section of the manual, by default 1, see man (7) man-pages
            for more info about existing sections
        - manual_title - the title of the manual, by default "Generated Python Manual",
            see man (7) man-pages for more instructions
        - include - a file of extra material to include; see below for the format
        - manfile - a file containing a complete man page that just needs to be installed
            (such files must also be listed in `MANIFEST.in`)
        
        The values from setup.cfg override values from setup.py's setup(). Note that
        when `manfile` is set for a particular page, no other option is allowed.
        
        Then run `setup.py build_manpages` to build a manpages for your project.  Also,
        if you used `get_build_py` helper, `setup.py build` then transitively builds the
        manual pages.
        
        ## Include file format
        
        The include file format is based on GNU `help2man`'s `--include` format.
        
        The format is simple:
        
        ```
        [section]
        text
        
        /pattern/
        text
        ```
        
        Blocks of verbatim *roff text are inserted into the output either at
        the start of the given `section` (case insensitive), or after a
        paragraph matching `pattern`, a Python regular expression.
        
        Lines before the first section are silently ignored and may be used for
        comments and the like.
        
        Other sections are prepended to the automatically produced output for the
        standard sections given above, or included near the bottom of the man page,
        before the `AUTHOR` section, in the order they occur in the include file.
        
        Placement of the text within the section may be explicitly requested by
        using the syntax `[<section]`, `[=section]` or `[>section]` to place the
        additional text before, in place of, or after the default output
        respectively.
        
        ## Installation
        
        This package is distributed [in PyPI][pypi-page], can be installed by:
        
            $ pip install argparse-manpage
        
        It can simply downloaded, or distributed as a git submodule (see above).
        
        
        ## Packaging status
        
        The Git snapshot RPMs–pre-release version automatically built from the `main`
        branch–are available in Fedora Copr build system
        
        [![build status](https://copr.fedorainfracloud.org/coprs/praiskup/argparse-manpage-ci/package/argparse-manpage/status_image/last_build.png)](https://copr.fedorainfracloud.org/coprs/praiskup/argparse-manpage-ci/)
        
        The `argparse-manpage` project is provided natively on many distributions:
        
        ![build status](https://repology.org/badge/vertical-allrepos/python:argparse-manpage.svg?exclude_unsupported=1&header=argparse-manpage)
        
        Try your package manager directly (e.g. on Fedora `dnf install -y
        argparse-manpage`).
        
        
        ## History
        
        The initial code was developed for CrunchyFrog, a database query tool for Gnome.
        The [frog] is now retired and [RunSQLRun] is it's successor.  Then, the
        `build_manpage` command was developed in [andialbrecht] and edited slightly
        in [gabrielegiammatteo].  There's even an [old blog post] about this command.
        
        Since some useful work has been done in [python pull request], the code from the
        PR has been used here too.
        
        Later more options and flexibility has been implemented in this fork, with the
        help of many contributors.  Thank you!
        
        Historically, `build_manpage` setup.py command was provided (mostly for
        `OptionParser`).  Later we migrated to more versatile `build_manpages` command.
        But the old variant is still [supported](examples/old\_format/README.md).
        
        ## License
        
        This work is released under the terms of the Apache License v2.0.
        See LICENSE for details.
        
        
        [^1]: `argparse-manpage` needs to process the location (file/module) via Python
              interpreter, and thus please avoid side-effects (typically, the `main.py`
              files need to use the `if __name__ == "__main__"` condition, and similar).
        
        [gabrielegiammatteo]: https://github.com/andialbrecht/build\_manpage
        [andialbrecht]: https://github.com/andialbrecht/build\_manpage
        [frog]: http://crunchyfrog.googlecode.com/svn/
        [RunSQLRun]: https://github.com/andialbrecht/runsqlrun
        [old blog post]: https://andialbrecht.wordpress.com/2009/03/17/creating-a-man-page-with-distutils-and-optparse/
        [python pull request]: https://github.com/python/cpython/pull/1169
        [ap-docs]: https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser
        [pypi-page]: https://pypi.org/project/argparse-manpage/
        
Platform: UNKNOWN
Description-Content-Type: text/markdown
Provides-Extra: setuptools
