Some feedback...
Ian Bicking
* Why not render static files? It's relatively simple compared to
rendering other files. This has always been very handy in Pudge. I
really would love to stop using Pudge. But building my own rendering
thing just for the static files seems kind of annoying.
* The function signature color is really really light. That's just odd.
The italics also seems odd to me.
* Having "self" in the parameter list for an instance method seems
redundant. Not sure what to do with a class method. Actually put
@classmethod in the text?
* Descriptors don't render well at all. I tried it with webob, and I
get lots of this:
Value of
None
I don't quite know why the name doesn't show up. These descriptors
all have __doc__ attributes. After a bit of tweaking in Pudge it all
worked okay.
* What's up with all the TOP links? Seems very old school, and not that
useful.
* Anchors throughout the page would be nice. The little purple hover
links to those anchors would also be nice.
* If the navigation on the left floated, that would also be really nice.
Anyway, I'm glad to see someone working on this stuff, and what's there
looks pretty good so far.
--
Ian Bicking : ia...@colorstudy.com : http://blog.ianbicking.org
Daniel Haus
> * Why not render static files? It's relatively simple compared to
> rendering other files. This has always been very handy in Pudge. I
> really would love to stop using Pudge. But building my own rendering
> thing just for the static files seems kind of annoying.
Hi Ian! Maybe it's too early in the morning, but I have no idea what
you mean by "render static files". Could you give an example?
> * The function signature color is really really light. That's just
> odd.
> The italics also seems odd to me.
That's because initially I wasn't totally sure if I should include it
at all. When I made it darker and better readable, it cluttered the
page up, so I made it less annoying, but also less readable.I
personally like it. the way it is, but it's themable anyway.
> * Having "self" in the parameter list for an instance method seems
> redundant.
Yep, but that's what inspect.getargspec/formatargspec returns, so
modifying it felt unnatural and not wise to me.
> Not sure what to do with a class method. Actually put
> @classmethod in the text?
One thing I totally forgot about is decorators. I neither implemented
any support nor tested them at all. How careless. I will have to look
into this.
> * Descriptors don't render well at all. I tried it with webob, and I
> get lots of this:
>
> Value of
>
> None
>
> I don't quite know why the name doesn't show up. These descriptors
> all have __doc__ attributes. After a bit of tweaking in Pudge it all
> worked okay.
Gerard already pointed me at a bug with attributes in general [1].
I'll have a look at that, too.
> * What's up with all the TOP links? Seems very old school, and not
> that
> useful.
Yes, but possibly a bit useful to some people. Possibly not. Maybe I
really should take that out. I'll have to think the whole default
theme over anyway.
> * Anchors throughout the page would be nice. The little purple hover
> links to those anchors would also be nice.
Excuse me, I don't get that. What "little purple hover links"?
> * If the navigation on the left floated, that would also be really
> nice.
I was thinking about that, too, and actually originally it was
floating. But then again, I wanted the default theme to be as static,
compatible, minimalistic and scriptless as possible. One point on my
Todo-List is to add a few more themes, which should include at least
one with a floating sidebar.
> Anyway, I'm glad to see someone working on this stuff, and what's
> there
> looks pretty good so far.
Thank you, Ian. Looks like it's still a long road to a 0.1.0-release.
[1] http://groups.google.com/group/apydia/browse_thread/thread/1b894958f79c18a4
--
Daniel Haus
http://ematia.de
grflanagan
On Dec 19, 8:42 am, Daniel Haus <daniel.h...@ematia.de> wrote:
> Am 19.12.2007 um 00:53 schrieb Ian Bicking:
>
> > * The function signature color is really really light. That's just
> > odd.
> > The italics also seems odd to me.
>
> That's because initially I wasn't totally sure if I should include it
> at all. When I made it darker and better readable, it cluttered the
> page up, so I made it less annoying, but also less readable.I
> personally like it. the way it is, but it's themable anyway.
>
lighter #CCC - but I like the italics.
> > * Having "self" in the parameter list for an instance method seems
> > redundant.
>
> Yep, but that's what inspect.getargspec/formatargspec returns, so
> modifying it felt unnatural and not wise to me.
>
think of the following changes to `descriptors.py`:
* In FunctionDesc.__init__ replace
self.argspec = formatargspec(*getargspec(function))
with
self._argspec = getargspec(function)
Then make `argspec` a property:
@property
def argspec(self):
return formatargspec(*self._argspec)
Which means you can change MethodDesc's behaviour by overriding it's
__init__ :
def __init__(self, method):
super(MethodDesc, self).__init__(method)
self._argspec[0].remove('self')
?
This worked for my setup with no problems.
Gerard
Daniel Haus
Am 19.12.2007 um 10:18 schrieb grflanagan:
> On Dec 19, 8:42 am, Daniel Haus <daniel.h...@ematia.de> wrote:
>> Am 19.12.2007 um 00:53 schrieb Ian Bicking:
>>> * The function signature color is really really light. That's just
>>> odd.
>>> The italics also seems odd to me.
>>
>
> I agree with Ian about the colour - I have #777 rather than the
> lighter #CCC - but I like the italics.
Ok, I'll try that, thanks.
>>> * Having "self" in the parameter list for an instance method seems
>>> redundant.
>>
>
> Yes, agree again - I was going to make the point myself. What do you
> think of the following changes to `descriptors.py`:
[...]
Looks great. I'll put that ine as soon as I find the time.
Thanks!
Ian Bicking
> Am 19.12.2007 um 00:53 schrieb Ian Bicking:
>
>> * Why not render static files? It's relatively simple compared to
>> rendering other files. This has always been very handy in Pudge. I
>> really would love to stop using Pudge. But building my own rendering
>> thing just for the static files seems kind of annoying.
>
> Hi Ian! Maybe it's too early in the morning, but I have no idea what
> you mean by "render static files". Could you give an example?
Just text files. What you go out of your way to say apydia won't render
;) With pudge I can update all my docs for a project with just "python
setup.py pudge publish", and it all links up properly and gets uploaded.
I really like that.
>> * The function signature color is really really light. That's just
>> odd.
>> The italics also seems odd to me.
>
> That's because initially I wasn't totally sure if I should include it
> at all. When I made it darker and better readable, it cluttered the
> page up, so I made it less annoying, but also less readable.I
> personally like it. the way it is, but it's themable anyway.
Yeah; I just know most people will use the default theme. A function
name without its signature doesn't mean much to me, I guess.
Have you seen the 2.6 docs? It's a pretty big change, and might inform
the style some: http://docs.python.org/dev/library/os.path.html
>> * Having "self" in the parameter list for an instance method seems
>> redundant.
>
> Yep, but that's what inspect.getargspec/formatargspec returns, so
> modifying it felt unnatural and not wise to me.
In, say, Zope interfaces they always remove self, since the caller
doesn't pass it in -- it's more like an implementation detail of the
method. Though they also separate class and instance interfaces, which
is kind of awkward.
>> Not sure what to do with a class method. Actually put
>> @classmethod in the text?
>
> One thing I totally forgot about is decorators. I neither implemented
> any support nor tested them at all. How careless. I will have to look
> into this.
It's a little tricky, there's no general way for every decorator. Class
methods work okay apparently. Properties don't, since they just have a
__doc__.
There's some new function signature stuff coming in Python 2.6, I think?
Hopefully the inspect module abstract that away, but I'm not sure.
Anyway, that would make decorators a bit cleaner (less *args, **kw, and
more real signatures).
>> * Descriptors don't render well at all. I tried it with webob, and I
>> get lots of this:
>>
>> Value of
>>
>> None
>>
>> I don't quite know why the name doesn't show up. These descriptors
>> all have __doc__ attributes. After a bit of tweaking in Pudge it all
>> worked okay.
>
> Gerard already pointed me at a bug with attributes in general [1].
> I'll have a look at that, too.
>
>
>> * What's up with all the TOP links? Seems very old school, and not
>> that
>> useful.
>
> Yes, but possibly a bit useful to some people. Possibly not. Maybe I
> really should take that out. I'll have to think the whole default
> theme over anyway.
>
>
>> * Anchors throughout the page would be nice. The little purple hover
>> links to those anchors would also be nice.
>
> Excuse me, I don't get that. What "little purple hover links"?
They've gone by different names and I'm not sure what the best
implementation is now. If you hover over the leading paragraphs there's
a light ś that appears that is a link to that paragraph.
Oh, I notice they are in the dev Python docs; probably you could just
rip out their implementation. They also have code to highlight the
target, which is nice (when you link to an anchor, the anchored text
gets a yellow background).
>> * If the navigation on the left floated, that would also be really
>> nice.
>
> I was thinking about that, too, and actually originally it was
> floating. But then again, I wanted the default theme to be as static,
> compatible, minimalistic and scriptless as possible. One point on my
> Todo-List is to add a few more themes, which should include at least
> one with a floating sidebar.
I assume it would all just be Javascript, so it's still static and
minimal. It occurred to me as an alternative to the TOP links, since
then there will always be links on the screen to take you to the other
sections.
Daniel Haus
> Just text files. What you go out of your way to say apydia won't
> render
> ;) With pudge I can update all my docs for a project with just
> "python
> setup.py pudge publish", and it all links up properly and gets
> uploaded.
> I really like that.
Ok, I see. The reason for that is, that I only need an API doc
renderer, nothing more. I like to use other systems for website
creation (either Trac/Wiki or write down HTML manually). On the other
hand, if you miss that functionality, many others will miss it too. I
guess it's not too hard work to get that part implemented, so I
consider delivering that in a coming release. Would I have to remove
the bogus Die Hard quote then?
> Yeah; I just know most people will use the default theme. A function
> name without its signature doesn't mean much to me, I guess.
>
> Have you seen the 2.6 docs? It's a pretty big change, and might
> inform
> the style some: http://docs.python.org/dev/library/os.path.html
No I haven't. This would've been really helpful back then. However,
I'll take a closer look at it to find some inspiration, looks great.
> In, say, Zope interfaces they always remove self, since the caller
> doesn't pass it in -- it's more like an implementation detail of the
> method.
Good point, you're right, I'll remove that.
>>> * Anchors throughout the page would be nice. The little purple
>>> hover
>>> links to those anchors would also be nice.
>>
>> Excuse me, I don't get that. What "little purple hover links"?
>
> They've gone by different names and I'm not sure what the best
> implementation is now. If you hover over the leading paragraphs
> there's
> a light ¶ that appears that is a link to that paragraph.
Nice idea, I've seen these things (doesn't Trac use this technique?),
but never consciously taken notice of. Looks useful.
> Oh, I notice they are in the dev Python docs; probably you could just
> rip out their implementation. They also have code to highlight the
> target, which is nice (when you link to an anchor, the anchored text
> gets a yellow background).
Alright, I'll have a look at that, too.
> I assume it would all just be Javascript, so it's still static and
> minimal. It occurred to me as an alternative to the TOP links, since
> then there will always be links on the screen to take you to the other
> sections.
I wanted to totally avoid any JS in the default theme. But a much
better solution would be to supply a basic, minimalistic core theme
and to make the default theme fully featured as most people will use
it, well, by default.
Mark Ramm
> renderer, nothing more. I like to use other systems for website
> creation (either Trac/Wiki or write down HTML manually). On the other
> hand, if you miss that functionality, many others will miss it too. I
> guess it's not too hard work to get that part implemented, so I
> consider delivering that in a coming release. Would I have to remove
> the bogus Die Hard quote then?
What I would consider to be the killer feature of such a documentation
system is the ability to include sourcecode in my project
documentation from working tested examples. So, in addition to
embedding the source in the example text we could put some kind of
marker saying grab lines 22-55 of this python file and stick it in
here....
Sometimes doctests do the trick, but when you want to write about a
whole sample project that you develop with TurboGears or whatever it's
nice to be able to include code from real project files.
--Mark Ramm
Ian Bicking
FWIW I tried to do that a long time ago (basically with a precompiler)
and I was never able to maintain it well. It was kind of a
proto-doctest notion, where you'd write working example scripts, then
mark up pieces with #start XXX...#end XXX, and then in the docs say
#include XXX.
Which doesn't mean it couldn't be done better than how I did it, but at
least for me, I found it really hard to maintain.
Ian
percious
Daniel Haus
Am 22.12.2007 um 00:40 schrieb Mark Ramm:
> What I would consider to be the killer feature of such a documentation
> system is the ability to include sourcecode in my project
> documentation from working tested examples. So, in addition to
> embedding the source in the example text we could put some kind of
> marker saying grab lines 22-55 of this python file and stick it in
> here....
Interesting. Such a thing wouldn't be too hard to implement. Maybe a
docstring-preprocessor, possibly even an abstract, pluggable
mechanism? I'll take some time to think about that.
> Sometimes doctests do the trick, but when you want to write about a
> whole sample project that you develop with TurboGears or whatever it's
> nice to be able to include code from real project files.
Yes, maybe it'd be nice to allow including source from arbitrary URLs
by line numbers or even by symbol, like say:
[include source http://apydia.ematia.de/svn/apydia/trunk/apydia/project.py
#20-25]
or
[include source ../examples/sample3.py ExampleClass1]
If you have more suggestions, ideas or wishes, let me know!