Colorizing source code in docstrings

[Alberto]

Hi,

First of all, congratulations for the release! I've managed to create
a config file to generate API docs for ToscaWidgets quite easily and
the results are awesome! After I create I nice CSS file and theme
they'll soon be online. :)

Now the question: Does apydia provide a way to colorize source inside
docstrings with pygments? I have a hacked docutils parser extension to
do so somewhere (borrowed from pudge) but If Apydia already provides a
mechanism it would be much easier. If not I could try to implement
something to contribute...

Thanks for your effort!

Alberto

[Daniel Haus]

Thank you, Alberto. I'm very happy that it works for you - and it's a
great feeling to be able to give something back to the community.

Now, here's the answer to your question:
Sourcecode highlighting should work out of the box for reST and
Markdown (I haven't really looked at Textile yet). As a good example
for reST, see:
http://elixir.ematia.de/apidocs/elixir.ext.associable.html

And here's the sources:
http://elixir.ematia.de/svn/elixir/trunk/elixir/ext/associable.py

ie. all you need to do is to prepend a ".. sourcecode:: python" to
your code snippets.

For Markdown you'll have to put some shebang-construct in front of the
source code, eg:

#!python
def f(x):
return x*x

I guess I should document that.

Great to hear you'll be using Apydia for the ToscaWidgets API docs,
which I again use very frequently. I can't wait to see a ToscaWidget-
theme. Please let me know if my Photoshop, TextMate and me can be of
any help...

Greetings,

[Alberto]

On Nov 30, 5:40 pm, Daniel Haus <daniel.h...@gmail.com> wrote:
> Thank you, Alberto. I'm very happy that it works for you - and it's a
> great feeling to be able to give something back to the community.
>
> Now, here's the answer to your question:
> Sourcecode highlighting should work out of the box for reST and
> Markdown (I haven't really looked at Textile yet). As a good example
> for reST, see:
> http://elixir.ematia.de/apidocs/elixir.ext.associable.html
>
> And here's the sources:
> http://elixir.ematia.de/svn/elixir/trunk/elixir/ext/associable.py
>
> ie. all you need to do is to prepend a ".. sourcecode:: python" to
> your code snippets.

Aha, I was using ".. code-block:: Python"... I've made a global search
and it worked great!

FYI, The latest TW trunk (twForms will come soon) is now using apydia
for docs.
To generate them just "python setup.py apydia" (well, you know
better... just saying this because I'm cross-posting to TW list so
people there know there are nice API docs available and how they can
generate them until I put them online)

> (...)

>
> Great to hear you'll be using Apydia for the ToscaWidgets API docs,
> which I again use very frequently. I can't wait to see a ToscaWidget-
> theme. Please let me know if my Photoshop, TextMate and me can be of
> any help...

Are you serious? I'd *really* appreciate some photoshop and graphics
help!! You have total creativity freedom regarding the look you'd like
to give the theme. I like the Elixir theme a lot (which I suppose it's
yours?) so I know you're trustable ;)

Thanks! :)

Alberto

[Waylan Limberg]

First, as one of the core markdown devs, I'd like to say that I'm
excited to see support for markdown. That has been an itch I've wanted
scratched for some time.

To add to that, I see you are also using a stripped down version of my
CodeHilite extension for markdown. That's excellent! I've been
debating weather I should do the same to the extension. I first
started that extension before Pygments (even before there was an
extension api for markdown), so all the non-pygments stuff came first.
When I first discovered pygments, I just added it into the existing
api. Now I don't see any need for the other stuff.

Anyway, I have never received any feedback on the syntax for
specifying the language used on code blocks. As there is no
established convention in markdown in general, I came up with my own.
So, yeah, you probably should document it. Of course, I'm open to
other/better suggestions.

--
----
Waylan Limberg
way...@gmail.com

[Daniel Haus]

On 30 Nov., 19:26, "Waylan Limberg" <way...@gmail.com> wrote:
> First, as one of the core markdown devs, I'd like to say that I'm
> excited to see support for markdown. That has been an itch I've wanted
> scratched for some time.

For some strange reason I first wanted to go with Textile. Then
Jonathan LaCour suggested Markdown and now I think it's by far the
best choice. I only set reST as a default to simplify the transition
for pudge-users a bit. I use and officially recommend Markdown. Still
I want to keep that part (and most other parts) pluggable for
compatibility reasons and for extensibility.

> To add to that, I see you are also using a stripped down version of my
> CodeHilite extension for markdown. That's excellent! I've been
> debating weather I should do the same to the extension. I first
> started that extension before Pygments (even before there was an
> extension api for markdown), so all the non-pygments stuff came first.
> When I first discovered pygments, I just added it into the existing
> api. Now I don't see any need for the other stuff.

Funny, I did use your extension up to the point, when I figured out
that I had no idea how to easy_install the extension. I could've asked
you, but I wanted to get my release out as fast as possible, so I
decided to quickly copy the corresponding parts of your code.

> Anyway, I have never received any feedback on the syntax for
> specifying the language used on code blocks. As there is no
> established convention in markdown in general, I came up with my own.

Too bad you didn't receive any feedback. Your solution is the best I
can think of (especially as a UNIX lover) and the one that feels most
natural to me. I'd clearly vote for it to become the standard way, if
anyone asked me.

> So, yeah, you probably should document it. Of course, I'm open to
> other/better suggestions.

No, please let's keep it as it is and document it. I need much more
documentation (about how to write docstrings, create themes etc.), so
I'll redo the sparse documentation part of the Apydia website anyway.

--
Daniel Haus
http://ematia.de