xml_write - maybe add a few samples for this

[werner]

Hi,

Making progress with Amara without too many issues yet.

Figuring out what I needed to give to doc.xml_write(stream=fileObj) so it would write to a file took me a moment and was more of a guess then anything else.  Maybe add a few samples to the tutorial or the http://wiki.xml3k.org/Amara/QuickRef

I am using WingIDE to develop and it is pretty good and providing code tips and its code assistance is very good - except for Amara.  Are any of you using WingIDE and have some tips on how to improve on this.

Are there any plans for e.g. Sphinx based documentation?  Tried to generate something yesterday, but besides having to work around some import tricks you do in Amara I still end up with over 2,000 errors and not much documentation at the end.  If Sphinx doc would be of interest I can try to work out the problems but it would also mean that the doc strings would need to be improved, written .....

Werner

[Luis Miguel Morillas]

El día 21 de abril de 2012 12:49, werner <werner...@sfr.fr> escribió:
> Hi,
>
> Making progress with Amara without too many issues yet.
>

Cool

> Figuring out what I needed to give to doc.xml_write(stream=fileObj) so it
> would write to a file took me a moment and was more of a guess then anything
> else.  Maybe add a few samples to the tutorial or the
> http://wiki.xml3k.org/Amara/QuickRef
>

Ok. This is more info about writing http://wiki.xml3k.org/Amara/Writing

> I am using WingIDE to develop and it is pretty good and providing code tips
> and its code assistance is very good - except for Amara.  Are any of you
> using WingIDE and have some tips on how to improve on this.
>
> Are there any plans for e.g. Sphinx based documentation?  Tried to generate
> something yesterday, but besides having to work around some import tricks
> you do in Amara I still end up with over 2,000 errors and not much
> documentation at the end.  If Sphinx doc would be of interest I can try to
> work out the problems but it would also mean that the doc strings would need
> to be improved, written .....
>

Most of the documents are in the wiki (http://wiki.xml3k.org) because
it's a better tool for collaboration. Maybe we could convert wiki docs
to sphinxs docs so we could build an sphinx site at xml3k or at
readthedocs.org

Thanks, Werner.

Regards,

-- luismiguel

> Werner
>
> --
> You received this message because you are subscribed to the Google Groups
> "akara" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/akara/-/JUHmIb-8VnEJ.
> To post to this group, send email to ak...@googlegroups.com.
> To unsubscribe from this group, send email to
> akara+un...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/akara?hl=en.

[Werner]

Hi Luis,

On 21/04/2012 15:34, Luis Miguel Morillas wrote:
...

>> Figuring out what I needed to give to doc.xml_write(stream=fileObj) so it
>> would write to a file took me a moment and was more of a guess then anything
>> else. Maybe add a few samples to the tutorial or the
>> http://wiki.xml3k.org/Amara/QuickRef
>>
> Ok. This is more info about writing http://wiki.xml3k.org/Amara/Writing

Thanks, for that link.

I think it would still be nice to add that to the QuickRef.

..
> Most of the documents are in the wiki (http://wiki.xml3k.org) because
> it's a better tool for collaboration. Maybe we could convert wiki docs
> to sphinxs docs so we could build an sphinx site at xml3k or at
> readthedocs.org

I wasn't thinking of replacing the wiki, but more of having an Sphinx
auto generated API doc of Amara in addition to the wiki.

Andrea Gavana does a really neat job for wxPython on this:
http://xoomer.virgilio.it/infinity77/Phoenix/lib.agw.aui.framemanager.html#module-lib.agw.aui.framemanager

I have used an older version of his generation code to do some
sample/test doc for some wxPython/SQLAlchemy demo stuff I have done with
Mike D.:
http://thewinecellarbook.com/medialocker/mlsrc.controllers.d_book.Book.html

I used that code to generate doc for Amara, but it would require quite a
bit of work. Got a lot of Sphinx errors which I haven't looked at in
detail, but I am guessing that the code which generates the .rst files
from the Amara code Sphinx has some problems how things are done in
Amara - at least out of the box.

I could try to work on this but it would only make sense if the Amara
developers sign up for it and write/update the doc strings to be
Sphinx/.rst compatible.

Werner

[Uche Ogbuji]

On Sat, Apr 21, 2012 at 8:17 AM, Werner <werner...@sfr.fr> wrote:

Hi Luis,

On 21/04/2012 15:34, Luis Miguel Morillas wrote:
...

Figuring out what I needed to give to doc.xml_write(stream=fileObj) so it
would write to a file took me a moment and was more of a guess then anything
else.  Maybe add a few samples to the tutorial or the
http://wiki.xml3k.org/Amara/QuickRef

Ok. This is more info about writing http://wiki.xml3k.org/Amara/Writing

Thanks, for that link.

I think it would still be nice to add that to the QuickRef.

Yes. I'll try to get that updated today.

 

Most of the documents are in the wiki (http://wiki.xml3k.org) because
it's a better tool for collaboration. Maybe we could convert wiki docs
to sphinxs docs so we could build an sphinx site at xml3k or at
readthedocs.org

I wasn't thinking of replacing the wiki, but more of having an Sphinx auto generated API doc of Amara in addition to the wiki.

Yeah, we discussed doing this in the past, but no one has had a chance to do it.  Thanks for giving it a try. I'd be happy to help you where I can because i think it's well worth doing.  Our previous discussions were about generating Docbook from Moin, but this Sphinx idea sounds even better.

 

Andrea Gavana does a really neat job for wxPython on this:
http://xoomer.virgilio.it/infinity77/Phoenix/lib.agw.aui.framemanager.html#module-lib.agw.aui.framemanager

I have used an older version of his generation code to do some sample/test doc for some wxPython/SQLAlchemy demo stuff I have done with Mike D.:
http://thewinecellarbook.com/medialocker/mlsrc.controllers.d_book.Book.html

I used that code to generate doc for Amara, but it would require quite a bit of work.  Got a lot of Sphinx errors which I haven't looked at in detail, but I am guessing that the code which generates the .rst files from the Amara code Sphinx has some problems how things are done in Amara - at least out of the box. 

I could try to work on this but it would only make sense if the Amara developers sign up for it and write/update the doc strings to be Sphinx/.rst compatible.

Thanks for offering to lead. Could you post a few examples of how docstrings would have to change? If it seems reasonable, I can sign up to take on some of the burden of making the updates.

Incidentally you mentioned the tons of errors you get from the Amara test suite. Alas that's the problem Luis alluded to before. The test suites were largely copied from 4Suite and Amara 1.x.  Much of the new functionality has working test suites, but the older stuff need a lot of work to get into shape, and again no one has had much time. This, as Luis pointed out, is the biggest part of  our reluctance to move out of alpha status.

--
Uche Ogbuji                       http://uche.ogbuji.net
Weblog: http://copia.ogbuji.net
Poetry ed @TNB: http://www.thenervousbreakdown.com/author/uogbuji/
Founding Partner, Zepheira        http://zepheira.com
Linked-in: http://www.linkedin.com/in/ucheogbuji
Articles: http://uche.ogbuji.net/tech/publications/
Friendfeed: http://friendfeed.com/uche
Twitter: http://twitter.com/uogbuji
http://www.google.com/profiles/uche.ogbuji

[Werner]

Hi Uche,

On 21/04/2012 16:54, Uche Ogbuji wrote:
...

> Thanks for offering to lead. Could you post a few examples of how
> docstrings would have to change? If it seems reasonable, I can sign up
> to take on some of the burden of making the updates.

They shouldn't be to drastic, haven't looked to much at the code, just
noticed in the generated doc that lots was missing or badly formatted.

The wxPython project came up with the following, which is basically
docutils/.rst/Sphinx influenced/defined.

http://xoomer.virgilio.it/infinity77/Phoenix/DocstringsGuidelines.html

>
> Incidentally you mentioned the tons of errors you get from the Amara
> test suite.

Sorry, the errors I was referring too have more to do with Sphinx and
how it reads the package to be documented.

As this is of interest I will have another go and come back here with
particular issues I run into which I can't explain/work around myself to
generate the Sphinx documentation.

Not sure when I get to this, but I will at least do a proof of concept,
hopefully within a week or two.

Werner

[Luis Miguel Morillas]

I added a new example on writing [1] .

Werner, if you want to collaborate with documentation on our wiki, we
can add you to the http://wiki.xml3k.org/UserGroup.

[1] http://wiki.xml3k.org/Amara/Tutorial#Writing_XML_.28and_HTML.29_from_nodes

-- luismiguel

>
> --
> You received this message because you are subscribed to the Google Groups
> "akara" group.