Nice work - but more docs please.
grflanagan
Nice work - just what I needed, thanks.
What there is of Apydia's own documentation is good (and looks great),
but I think there could be more newbie-directed info. Here are a few
things I had to figure out myself:
* for integration with distutils the docs would suggest that all you
had to provide was the appropriate section in 'setup.cfg', but it
doesn't say that you also have to add a
from apydia.command import apydia
and
setup(
....
cmdclass = {'apydia': apydia},
....
)
in setup.py
* the left-hand 'browser' section in the default theme didn't display
in IE - I fixed this by removing 'position: relative' from the #page
section in default.css ( I also removed 'position: static' from the
#browser section with no noticeable effect in IE or Firefox).
* I assumed (for no particular reason) that the different themes were
being picked up from the themes directory, so I added a new directory
'mytheme' containing a copy of the default theme files, and altered
the 'theme.ini' accordingly - but only got a ThemeNotFoundError. I
had to pick through the code - theme.py -> project.py -> command.py -
to see that it was a setuptools thing, and that I had to alter the
'entry_points.txt' file in EGG-INFO.
* It wasn't clear how to document function parameters and return
values - I had to go through existing source code to figure it out -
ie. :param var1: Description of var1 and :return: A list
* I have one module with a lot of decorated functions. At first these
were all appearing in the docs as `wrapper` which is the name of the
inner class in the decorator. I fixed this with `update_wrapper` from
the `functools` module (available from Python 2.5), but even so, the
function signature is not being picked up and appears as (*args,
**kwargs) which is the signature of `wrapper`. Currently, I have to
comment out all the decorator lines before generating the docs.
In addition, I don't know how to document module-level attributes,
they all appear with value= None.
(Also, having a link to the colourised source would be nice).
Hope this helps.
Thanks again.
Gerard
Daniel Haus
> Nice work - just what I needed, thanks.
I'm glad, you like it.
> What there is of Apydia's own documentation is good (and looks great),
> but I think there could be more newbie-directed info.
Absolutely right, there's a lot on my Apydia-todo-list, including
better documentation. I thought I'd better release it sooner than
later, so I only had the time to write the docs that are there now. I
will add more as soon as I find the time. Feedback like yours is
highly appreciated.
Until then, I hope everyone who's comfortable with setuptools and
quickly needs a replacement for Pudge can get it working easily.
> * for integration with distutils the docs would suggest that all you
> had to provide was the appropriate section in 'setup.cfg', but it
> doesn't say that you also have to add a
>
> from apydia.command import apydia
>
> and
>
> setup(
> ....
> cmdclass = {'apydia': apydia},
> ....
> )
>
> in setup.py
Not that I'm aware of. I never had to do that myself and I'm not even
sure what it exactly does. Could you give details on cases where this
would be necessary?
> * the left-hand 'browser' section in the default theme didn't display
> in IE - I fixed this by removing 'position: relative' from the #page
> section in default.css ( I also removed 'position: static' from the
> #browser section with no noticeable effect in IE or Firefox).
Ouch, that's evil. As a heavy Mac-user I always have to fire up some
virtual Windows installation to test the stylesheets in IE. Must have
missed that somehow before the release. I fixed that in r30, thank you.
> * I assumed (for no particular reason) that the different themes were
> being picked up from the themes directory, so I added a new directory
> 'mytheme' containing a copy of the default theme files, and altered
> the 'theme.ini' accordingly - but only got a ThemeNotFoundError. I
> had to pick through the code - theme.py -> project.py -> command.py -
> to see that it was a setuptools thing, and that I had to alter the
> 'entry_points.txt' file in EGG-INFO.
There should be at least a short howto on theming, you're perfectly
right.
> * I have one module with a lot of decorated functions. At first these
> were all appearing in the docs as `wrapper` which is the name of the
> inner class in the decorator. I fixed this with `update_wrapper` from
> the `functools` module (available from Python 2.5), but even so, the
> function signature is not being picked up and appears as (*args,
> **kwargs) which is the signature of `wrapper`. Currently, I have to
> comment out all the decorator lines before generating the docs.
Haven't done any testing on decorators yet. I'll have a look at it.
> In addition, I don't know how to document module-level attributes,
> they all appear with value= None.
Sounds like a bug.
> (Also, having a link to the colourised source would be nice).
If you're running Trac for your project, that's fairly easy. I
personally prefer navigating through sourcecode in my text editor, but
I can imagine many people are seeing that differently. I'll put that
on my list. In fact, I'll put your whole email on my list, it shows up
a lot of good points.
> Hope this helps.
Sure it does, thank you very much, Gerard.
--
Daniel Haus
http://ematia.de
grflanagan
Daniel,
Thanks for your reply.
On Dec 18, 10:01 am, Daniel Haus <daniel.h...@ematia.de> wrote:
> Am 17.12.2007 um 15:39 schrieb grflanagan:
>
>
> > * for integration with distutils the docs would suggest that all you
> > had to provide was the appropriate section in 'setup.cfg', but it
> > doesn't say that you also have to add a
>
> > from apydia.command import apydia
>
> > and
>
> > setup(
> > ....
> > cmdclass = {'apydia': apydia},
> > ....
> > )
>
> > in setup.py
>
> Not that I'm aware of. I never had to do that myself and I'm not even
> sure what it exactly does. Could you give details on cases where this
> would be necessary?
>
python setup.py apydia
I get 'Unrecognised option: apydia' (or similar) - but I see the
problem. In your (Apydia) setup.py you have
from setuptools import setup
where I have
from distutils import setup
in mine. So presumably setuptools is just doing implicitly what I'm
doing explicitly. The custom command syntax I gave above was taken
from here:
http://docs.python.org/dist/node32.html
>
> > In addition, I don't know how to document module-level attributes,
> > they all appear with value= None.
>
> Sounds like a bug.
>
In line 79 of the `module.html` template, change this:
<pre class="code"><code
py:content="helpers.pformat(helpers.safe_get(member, 'value'))" /></
pre>
to this:
<pre class="code"><span py:replace="member.value" /></pre>
or, in line 27 of helpers.py, change this:
return member.get(key, None)
to this:
return getattr(member, key)
It works for me at least.
All the best
Gerard
Daniel Haus
> I get 'Unrecognised option: apydia' (or similar) - but I see the
> problem. In your (Apydia) setup.py you have
>
> from setuptools import setup
>
> where I have
>
> from distutils import setup
>
> in mine. So presumably setuptools is just doing implicitly what I'm
> doing explicitly.
Ah, I see. Thank you, I'll add a comment about that.
>>> In addition, I don't know how to document module-level attributes,
>>> they all appear with value= None.
>>
>
> I found two ways to solve this:
> In line 79 of the `module.html` template, change this:
[...]
> or, in line 27 of helpers.py, change this:
>
> return member.get(key, None)
>
> to this:
>
> return getattr(member, key)
Yep, looks good, I'll fix that.
So once again, thanks a lot!
Ian Bicking
> * for integration with distutils the docs would suggest that all you
> had to provide was the appropriate section in 'setup.cfg', but it
> doesn't say that you also have to add a
>
> from apydia.command import apydia
>
> and
>
> setup(
> ....
> cmdclass = {'apydia': apydia},
> ....
> )
>
> in setup.py
and you just get an awkward import error if not. You could futz
around with catching the error and disabling the command, but an
easier way is to add this to your setup.cfg:
[global]
command_packages = apydia.command
This won't fail if the package isn't there. I use this for distutils
extensions that don't necessarily apply to every package, and then I
just add this to setup.cfg to enable the commands I want.
Unfortunately the commands don't show up with python setup.py --help-
commands
Ian
grflanagan
(Sorry, I missed your reply - Christmas chaos!) Thanks for the tip!
Gerard