Documenting Packages
Rob Cowie
After only minor exploration (5 minutes of use), I am unable to
produce documentation for an installed python package. Pointing to
modules within the packages works beautifully.
Does Apydia support the production of package docs?
If it does, does the package need to be configured in any particular
way? (i.e. have __init__.__all__ set)
cheers,
Rob Cowie
Daniel Haus
I'm not exactly sure what you mean by "package docs". If you mean if
Apydia is able to generate complete documentation from like a couple
of rst-files in eg. a doc-folder, just the way like pudge does, I'll
have to disappoint you.
Apydia generetes API reference documentation, nothing more (by
intention). That's, by the way, the reason for the slightly modified
die hard quote at the top of the website.
Greetings,
--
Daniel Haus
http://ematia.de
Rob Cowie
Sorry - didn't express myself clearly...
I have a package which contains two more packages and several modules;
package/
__init__.py
sub-package-1/
sub-package-2/
__init__.py
module.py
interesting-module-1.py
interesting-module-2.py
boring-module-1.py
If I try to generate the api documentation for this package thus
(apydia package), I get a blank index page with no module docs or
links.
If I point to a module explicitly (apydia package.interesting-
module-1) it produces the api doc for that module.
Should apydia be able to descend into the package and produce the
appropriate documentation? I have defined __all__ in the top-level
__init__.py so sub modules are explicitly listed.
cheers,
Rob Cowie
On Dec 11, 11:19 am, Daniel Haus <daniel.h...@ematia.de> wrote:
> Hi Rob,
>
> I'm not exactly sure what you mean by "package docs". If you mean if
> Apydia is able to generate complete documentation from like a couple
> of rst-files in eg. a doc-folder, just the way like pudge does, I'll
> have to disappoint you.
>
> Apydia generetes API reference documentation, nothing more (by
> intention). That's, by the way, the reason for the slightly modified
> die hard quote at the top of the website.
>
> Greetings,
>
> --
Daniel Haus
Am 11.12.2007 um 13:09 schrieb Rob Cowie:
> Should apydia be able to descend into the package and produce the
> appropriate documentation? I have defined __all__ in the top-level
> __init__.py so sub modules are explicitly listed.
So, the modules are listed in __all__. Hm, and they are imported in
this place, too? Would you let me have a look on your package/
__init__.py?
Rob Cowie
so that on 'from package import *', they are imported.
I will try importing them although this is not the behaviour I require
from this package. I don't really want the sub modules to be imported
into the app namespace when the package is imported.
FYI, the only line in __init__.py is...
__all__ = ['db', 'emailLib', 'log', 'passwords', 'ResolutionSorter',
'roman']
Daniel Haus
> The modules are not imported in __init__.py, merely listed in __all__
> so that on 'from package import *', they are imported.
>
> I will try importing them although this is not the behaviour I require
> from this package. I don't really want the sub modules to be imported
> into the app namespace when the package is imported.
Then you will (currently) have to specify all packages as arguments to
the "apydia"-command (or in the apydia-section your setup.cfg). Btw.
there's a __doc_all__ property which you can set instead of __all__
(or additionally).
I'll work on making Apydia handle this in a more intelligent way.
Thank you for showing this up.
Daniel Haus
> Should apydia be able to descend into the package and produce the
> appropriate documentation? I have defined __all__ in the top-level
> __init__.py so sub modules are explicitly listed.
I enhanced Apydia to automatically discover sub-packages in r36. That
means you just specify the top-level package(s) and it will
automatically descend the package tree to find all modules. Seems to
work for my projects, please let me know if it does the job for you or
if it breaks anything.
Greetings!
Andi Albrecht
looks good here, exclude_modules work as expected, too.
Happy New Year!
Andi
Daniel Haus
> Hey Daniel,
>
> looks good here, exclude_modules work as expected, too.
>
> Happy New Year!
>
> Andi
Great! Happy New Year!