Function doc as a parameter to the start and subcommand decorator functions. #40

Open
mjdorma opened this Issue Feb 18, 2014 · 2 comments

Comments

Projects
None yet
2 participants
Contributor

mjdorma commented Feb 18, 2014

In the past week I have found myself writing small decorators to patch in the doc before begins reads the doc from my function. This proposal simply allows the developer to provide a function doc string to begins through the decorator's constructor.

Currently this is what I have done to get around not having doc as a parameter:
https://gist.github.com/mjdorma/6145546

A simple example of the current state:

"""My module's documentation string"""
import begin

def add_doc(func):
    func.__doc__ = __doc__ 
    return func

@begin.start
@add_doc
def main():
    pass

By adding doc as a param we will enable:

"""My module's document string"""
import begin

@begin.start
def main(doc=__doc__):
    pass
Owner

aliles commented Feb 18, 2014

Can you explain further your use case for this? Why is the docstring not sufficient?

I'm not against this per say. More I want to be convinced before adding complexity to begins that there isn't a better solution.

On Tue, Feb 18, 2014 at 3:11 PM, Michael Dorman notifications@github.com
wrote:

In the past week I have found myself writing small decorators to patch in the doc before begins reads the doc from my function. This proposal simply allows the developer to provide a function doc string to begins through the decorator's constructor.
Currently this is what I have done to get around not having doc as a parameter:
https://gist.github.com/mjdorma/6145546
A simple example of the current state:

"""My module's document string"""
import begin
def add_doc(func):
    func.__doc__ = __doc__ 
    return func
@begin.start
@add_doc
def main():
    pass

By adding doc as a param we will enable:

"""My module's document string"""
import begin
@begin.start
def main(doc=__doc__):
    pass

Reply to this email directly or view it on GitHub:
#40

Contributor

mjdorma commented Feb 18, 2014

First example is when I want the module main to appear as the doc string, this ties in really well when building a Sphinx documented module, where the module is the main or a command line interface entry point.

As a second example, I have a package that installs platform specific files and builds a database of the install state. When I print the help for the main entry point to this package I dynamically update the help depending on what the state of the install database is.

Another dummy program example:

import begin

def install_meta():
    return dict(foo='blah')

def _doc_inserter(main):
    main.__doc__ = "The main with %(foo)s" % install_meta()
    return main

@begin.start
@_doc_inserter
def main():
    pass

Here is an example of patching in the version (a cheap win to print in out in the main's help doc):

import version
import begin

def _doc_inserter(main):
    main.__doc__ = "Foo blah (v%s)" % version.__version__
    return main

@begin.start
@_doc_inserter
def main():
    pass

aliles added the enhancement label Feb 18, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment