Outputting ReST Documents

[percious]

Nice work. I have a google code project, and I would like to use your
document system to create the API docs for my site. The only problem
is that google code wiki is completely based on ReST, so the xhtml/
html format is not going to work for me. I am assuming that you
output ReST because you support TRAC, so I was wondering if there was
a way to render documents the same way, but outputting them to
directory instead of a Trac Wiki.

Thanks,
chris

[Daniel Haus]

Unfortunately I have to admit, Apydia does not support (or integrate
into) Trac, yet. So far the only Trac-supportig feature is, that it
can link into Trac's sourcecode browser. If you're referencing to the
Elixir documentation [1], it's just a dirty hack. A customized
`site.html`-template on the one hand and all the Apydia-generated
pages are simple XHTML, uploaded via FTP, on the other.

Maybe I should think about implementing support for pluggable output
generators, instead of X/HTML only. For now I'm sorry for having to
tell you, that you will have to find another way - or wait for me to
find the time to implement such a solution.

Regards,
Daniel

[1] http://elixir.ematia.de/apidocs/elixir.html

--
Daniel Haus
http://ematia.de

[ionel]

any progress on the pluggable output format ?

[Daniel Haus]

Am 25.01.2008 um 17:06 schrieb ionel:

> any progress on the pluggable output format ?

No, sorry. Correct me, but in my eyes this would mean, Apydia would've
to be able to convert any source format into any other (like markdown
rST or anything). This is nothing I would like to implement. Okay, it
might be possible to utilize BeautifulSoup to convert X/HTML into rST
or whatever you like, but this is beyond the scope of Apydia.

[Ionel Maries Cristian]

i'm not saying to implement a converter - im just wondering if you would decouple the xhtml generator from the rest of the stuff in apydia - to ease adding generators for new formats

[Daniel Haus]

Am 25.01.2008 um 19:28 schrieb Ionel Maries Cristian:

> i'm not saying to implement a converter - im just wondering if you
> would decouple the xhtml generator from the rest of the stuff in
> apydia - to ease adding generators for new formats

Then it would have to pass the docstrings through, unprocessed? And
offer plaintext-templates instead of HTML-templates?

[Ionel Maries Cristian]

To be completely honest i'm thinking about how could i use apydia to output docs in some sort of wiki sintax format.

 

Having the doctrings in wiki sintax and outputting plaintext might be a solution.

[Daniel Haus]

Should be possible. Apydia could put the raw docstrings into plaintext
templates. I'm not sure when I could deliver such a functionality as
Apydia's todo-list is pretty long and I'm very busy currently. I'll
see what I can do.

[Ionel Maries Cristian]

that would be very nice - my intentions are to integrate the doc generation with the googlecode wiki.

perhaps i could help somehow ?

[Daniel Haus]

Am 26.01.2008 um 03:54 schrieb Ionel Maries Cristian:

> that would be very nice - my intentions are to integrate the doc
> generation with the googlecode wiki.
> perhaps i could help somehow ?

If you could provide a kind of mockup, how the output should look
like, that'd be great. I have no idea how to render menus etc.

[Ionel Maries Cristian]

suppose you have a module mymodule, submodules mysubmodule, mysecsubmodule and a class mymodule.mysubmodule.MyClass
 
resulting file layout should be similar to the xhtml one but:
- filenames are in camel-case: MymoduleMysubmoduleMyClass.wiki instead of mymodule.mysubmodule.MyClass.html
 
content layout should be very simple - if there's a menu just dump it at the start of the document:
a example for mymodule.mysubmodule.MyClass:
 
#sumary mymodule.mysubmodule.MyClass api documentation
 
==== Modules: [MymoduleMysubmodule mymodule.mysubmodule] [MymoduleMysecsubmodule mymodule.mysecsubmodule] ===
==== Classes: [MymoduleMysubmoduleMyClass mymodule.mysubmodule.MyClass] ===
==== Methods [#some_meth some_meth] ===
==== Attributes [#some_attr some_attr] ===
 
= Class: mymodule.mysubmodule.MyClass =
 
Docstring
 
== Methods ==
 
=== some_meth ===
params: a, b='bla'
 
Docstring
 
== Attributes ==
 
=== some_attr ===
 
Docstring
 
 
 
How do you intend to approach this?

--
http://code.google.com/p/cogen/
ionel.

[Daniel Haus]

Great! Thank you, Ionel, this helps a lot.

I put this on top of my Apydia-todo-list. Hopefully I can get to this
in the next few days.

Greetings

[Ionel Maries Cristian]

Thank you too. Looking forward to it.

[Daniel Haus]

Accordingly to your example code I have modified Apydia and added a
"codewiki" theme. You can fetch it from trunk (r40).

I don't have any google code project to test this with, so please let
me know if it works and how it looks like.

The .ini-file I used for testling looks like this:

> [apydia]
>>
> title = My Google Code Project
> theme = codewiki
> docformat = plain
> modules = myproject
> destination = api-wiki
> verbose = True

Please note that I restructured the options-system and that some
options have changed in r40.

Greetings!

[Ionel Maries Cristian]

I've got it and checked in a quick stab at the docs.

Check them out here: http://code.google.com/p/cogen/wiki/CogenCore

Though I haven't fixed the docstrings for all the stuff yet.

 

I've done some modifications to the theme, you can find it here: http://cogen.googlecode.com/svn/trunk/cogen/docs/wikitheme/

Thanx

[Daniel Haus]

Am 01.02.2008 um 22:29 schrieb Ionel Maries Cristian:

> I've got it and checked in a quick stab at the docs.
> Check them out here: http://code.google.com/p/cogen/wiki/CogenCore
> Though I haven't fixed the docstrings for all the stuff yet.

Nice!

> I've done some modifications to the theme, you can find it here: http://cogen.googlecode.com/svn/trunk/cogen/docs/wikitheme/

I applied your modifications in r45, thank you.

[percious]

Awesome job guys. I'm going to take a look at this in the next week
or so, and put it up on dbsprockets. I'll give you guys a credit too.