On Fri, Jan 07, 2011 at 02:15:46PM +0100, Georg Brandl wrote: > Am 07.01.2011 14:11, schrieb Jakob Malm: > > On 7 Jan, 10:23, Georg Brandl <ge...@python.org> wrote: > >> > >> > which works fine. But how can I extract the docstrings from my utility > >> > scripts? > >> > >> You can't do that with autodoc if they are not importable. > > > > If you organize your utility scripts like this you will at least be > > able to get the docstring for the module (file), and data defined: > > > > """ > > Docstring for the script. > > > > """ > > > > #: Some data that you want autodoc to catch > > SOME_SETTING = 1 > > > > if __name__ == '__main__': > > # Your code goes here... > > # but autodoc won't see it, since __name__ != '__main__' when the > > python file is imported. > > Yes; the only problem is that scripts often have names that aren't valid > module names, and so cannot be imported, only directly executed.
This also means they cannot be unit-tested. If a name-like-this is desirable for a script, I'd be inclined to keep it short, e.g.: #!/usr/bin/python import mypackage.scripts.namelikethis namelikethis.main() and move the bulk of the code into an importable module. Another advantage of this is that you can then use setuptools entry points for creating console scripts. There are tools (e.g. zc.buildout[*]) that do not support distutils scripts, but support setuptools entry points. [*] https://bugs.launchpad.net/zc.buildout/+bug/422724 Marius Gedminas -- If I open a closet and there's a box in it and I have no idea what is in the box because I have not opened it since 1996, I will strongly take under consideration the possibility of contemplating a general study of the feasibility of chucking the box or at least moving it to one side. -- James Nicoll's Box Rule
signature.asc
Description: Digital signature
