Sphinx doc

[Werner]

Hi,

As I made much better progress in converting my vinoXML (some wine
specific format) export from Amara 1.x to 2.x then I expected - it is
basically done just needs some more clean up, but lots of that is
related the other application in my new version, I had a another go at
generating Sphinx doc for Amara 2.

Some notes on problems I run into.

- .py file encoding errors, it would be good if all .py files had this
as the first line "# -*- coding: utf-8 -*-#" and be properly encoded.
Just run into it with "amara.lib.iri.py", adding the coding line and
saving it fixed it as far as Sphinx is concerned.

Following files generate import errors when I am generating the .rst
files (basically walking the folder structure and import the modules to
get at the classes, methods, functions).

Files causing an issue:
xpath.extensions.BuiltInExtFunctions
xpath.extensions.MathFunctions
xpath.locationpaths.axisspecifiers'
'xpath.locationpaths.predicates'

Package I needed to exclude "xslt.tree" as the __init__.py of it caused
an import issue

Will have another look at these later on and see if I find a way of
keeping them in the doc.

Excluded folders "test" (shouldn't be an issue) and "tools".

After that I build it and it generates what you can see here (put it
temporarily onto my site):
http://thewinecellarbook.com/amaraTemp/
http://thewinecellarbook.com/amaraTemp/bindery.nodes.entity_base.html

I am still getting over 200 Sphinx build errors (much better then the
two thousand I had the other day:-) ) which I will start chasing down.

I get mainly these type of errors:
<autodoc>:: WARNING: Duplicate explicit target name:
"amara.bindery.model.attribute_constraint".

Either 'attribute_constraint' is defined twice or the extracter messed up.

Obviously still a lot of work before it is usable.
- Initial page needs to be filled with some better nicer content, e.g.
an overview, maybe some history ..... etc.
- samples such as how to use xml_write would be nice to have them e.g. here:
http://thewinecellarbook.com/amaraTemp/amara.writers.html?highlight=xml_write
- more/better doc strings

Werner

[Uche Ogbuji]

On Sun, Apr 22, 2012 at 12:58 PM, Werner <werner...@sfr.fr> wrote:

<snip interesting updates>

- .py file encoding errors, it would be good if all .py files had this as the first line "# -*- coding: utf-8 -*-#" and be properly encoded. Just run into it with "amara.lib.iri.py", adding the coding line and saving it fixed it as far as Sphinx is concerned.

Yeah, I do often forget to add the encoding line. We'll just have to catch up in doing so.

 

Following files generate import errors when I am generating the .rst files (basically walking the folder structure and import the modules to get at the classes, methods, functions).

Files causing an issue:
xpath.extensions.BuiltInExtFunctions
xpath.extensions.MathFunctions
xpath.locationpaths.axisspecifiers'
'xpath.locationpaths.predicates'

Package I needed to exclude "xslt.tree" as the __init__.py of it caused an import issue

Will have another look at these later on and see if I find a way of keeping them in the doc.

Excluded folders "test" (shouldn't be an issue) and "tools".

After that I build it and it generates what you can see here (put it temporarily onto my site):
http://thewinecellarbook.com/amaraTemp/
http://thewinecellarbook.com/amaraTemp/bindery.nodes.entity_base.html

Great! Any start is a good one.

 

I am still getting over 200 Sphinx build errors (much better then the two thousand I had the other day:-) ) which I will start chasing down.

I get mainly these type of errors:
<autodoc>:: WARNING: Duplicate explicit target name: "amara.bindery.model.attribute_constraint".

Either 'attribute_constraint' is defined twice or the extracter messed up.

Obviously still a lot of work before it is usable.
- Initial page needs to be filled with some better nicer content, e.g. an overview, maybe some history ..... etc.

I can start with this stuff. Should I just e-mail .rst files to this thread? Note: the trunk of Amara is on github, are you just going to keep on going and issue a pull request?

 

- samples such as how to use xml_write would be nice to have them e.g. here:
http://thewinecellarbook.com/amaraTemp/amara.writers.html?highlight=xml_write

That's just a matter of updating the docstring, right?

 

- more/better doc strings

Thanks.

--
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 23/04/2012 04:48, Uche Ogbuji wrote:

Obviously still a lot of work before it is usable.
- Initial page needs to be filled with some better nicer content, e.g. an overview, maybe some history ..... etc.

I can start with this stuff. Should I just e-mail .rst files to this thread?

I think it should be decided which road you like to go, is the sphinx-apidoc (what Luis Miguel used) "tweakable" enough to get the wanted end result or does it need a custom .rst generator.

Then ideally create a repo for it.

The overview is currently just one .rst file (see attached), could be further broken up if needed, everything else is in the doc strings.

Note: the trunk of Amara is on github, are you just going to keep on going and issue a pull request?

I run it against an installed "amara" but still have some import issues in the .rst generator, which it looks the sphinx-apidoc doesn't have as I see that e.g. amara.tree.node.xml_write is included in Luis Miguel's version.

 

- samples such as how to use xml_write would be nice to have them e.g. here:
http://thewinecellarbook.com/amaraTemp/amara.writers.html?highlight=xml_write

That's just a matter of updating the docstring, right?

Yes.

Werner

[Werner]

Hi,

Attached is a zip with the generation stuff.

To use it:
- update config.py with relevant path information (amara to doc path,
and path to tools)
- update source/conf.py with relevant path information (amara to doc path)

- makeRst.py html True - to do a full generation, it writes files to
tempsource and then only writes changed files to source, "html" defines
the builder, at this point no difference in makeRst for different
builder, "True/False" full or partial build

- makeSphinx.py html True, params have same meaning as above

- build/index.html to look at the result

Work to be done:
- remove all the widget screen shot stuff
- resolve the makeRst and makeSphinx errors

Werner

[Werner]

Hi,

On 23/04/2012 11:25, Werner wrote:
> Work to be done:
> - remove all the widget screen shot stuff

done, at the moment just commented

> - resolve the makeRst and makeSphinx errors

down to 45 errors which are the same then Luis Miguel is getting and a
few more in relation to FT and some other things.

One thing I am chasing and can not figure out is this.

In Luis Miguel's doc there is:
http://docs.xml3k.org/amara.html?highlight=xml_write#module-amara.tree

In it is a class "amara.tree.node".

If I look at amara.tree.py there is no such class in that file and a
search for "class node(" in the amara site-packages folder only gets a
hit in "amara.bindery.html.py".

So, where is this class coming from?

Werner

[Luis Miguel Morillas]

It's imported by amara.tree.py --> from amara._domlette import *

It's the C based part of Amara. This page could help:
http://wiki.xml3k.org/Amara/Architecture

-- lm
>
> Werner
>
> --
> You received this message because you are subscribed to the Google Groups
> "akara" group.
> 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,

On 23/04/2012 15:37, Luis Miguel Morillas wrote:
...

> It's imported by amara.tree.py --> from amara._domlette import * It's
> the C based part of Amara.

Hhm, the .rst builder is ignoring private things ("_" and "__", probably
a hang over when I did this for Dabo).

Fixed that, but get quit a few of this type of error now (following just
a few samples):

<autodoc>:0: WARNING: duplicate object description of
amara._expat.SaxReader, other instance in
h:\devProjectsT\SphinxDocs\Amara2\source\amara._expat.SaxReader.rst, use
:noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of
amara._expat.SaxReader, other instance in
h:\devProjectsT\SphinxDocs\Amara2\source\amara._expat.create_parser.rst,
use :noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of
amara.tree.attribute, other instance in
h:\devProjectsT\SphinxDocs\Amara2\source\amara.tree.attribute.rst, use
:noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of
amara.tree.attribute.xml_local, other instance in
h:\devProjectsT\SphinxDocs\Amara2\source\amara.tree.attribute.rst, use
:noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of
amara.tree.attribute.xml_name, other instance in
h:\devProjectsT\SphinxDocs\Amara2\source\amara.tree.attribute.rst, use
:noindex: for one of them
<autodoc>:0: WARNING: duplicate object description of
amara.tree.attribute.xml_namespace, other instance in
h:\devProjectsT\SphinxDocs\Amara2\source\amara.tree.attribute.rst, use
:noindex: for one of them

Are these multi definitions valid? If yes, I change the .rst generator
to add the ":noindex: to one of them.

Werner

[Werner]

Hi,

I uploaded the latest stuff to the temp location on my site, attached is
the stuff to build it.

http://thewinecellarbook.com/amaraTemp/index.html

Changed the index page to add a content section, also changed conf.py to
pick up the version number from amara.__version__.py and it includes now
the things I had missed before.

Have to do some other stuff but will get back to this towards the end of
the week or sometimes next week.

If anyone has comments on what is there now please give them "gently" to
me;-) . Would especially like to know if there is still something not
there at all or if something is included which should not be included.

Will then work on the following:
- fix the formatting errors in the doc strings, will start working on
this and provide patches
- including the C extension stuff generates some errors, see previous
post. Will fix them when I hear back on if the duplication definitions
should be there or not
- including the C extension also cause some errors with the inheritance
diagrams in some files, will fix those

Werner

[Luis Miguel Morillas]

Thanks, Werner,

I'll review it later.

Saludos,

-- luismiguel (@lmorillas)

[Sylvain Hellegouarch]

Hi

A great start. Obviously it shows that we lack tutorials and examples but it's a great starting point :) 

As a side note, I can't remember if Amara is using BitBucket or GitHub? They would clearly provide greater visibility and make it easy to participate here and there IMO. Even for ths docs.

--
- Sylvain
http://www.defuze.org
http://twitter.com/lawouach

[Werner]

On 24/04/2012 14:16, Sylvain Hellegouarch wrote:

> A great start. Obviously it shows that we lack tutorials and examples
> but it's a great starting point :)

Thanks.

>
> As a side note, I can't remember if Amara is using BitBucket or
> GitHub? They would clearly provide greater visibility and make it easy
> to participate here and there IMO. Even for ths docs.

https://github.com/zepheira/amara

Werner

[Sylvain Hellegouarch]

As a side note, I can't remember if Amara is using BitBucket or GitHub? They would clearly provide greater visibility and make it easy to participate here and there IMO. Even for ths docs.

https://github.com/zepheira/amara

Damn. The sad thing is that I'm actually subscribed to it as well. sigh. 

[Werner]

On 24/04/2012 14:34, Sylvain Hellegouarch wrote:

As a side note, I can't remember if Amara is using BitBucket or GitHub? They would clearly provide greater visibility and make it easy to participate here and there IMO. Even for ths docs.

https://github.com/zepheira/amara

Damn. The sad thing is that I'm actually subscribed to it as well. sigh.

I am happy to know that I am not the only one :-)  to whom things like this happen.

Now to the participate part of things.

- what is the best way to provide patches?  I locally use TortoiseHG and not git, cloned the git repo with THG, but how is one supplying patches.

I fixed a few of the indent errors, more as samples of what needs to be done, i.e. don't go and apply the two patches.

1. In xpath.util.simple_evaluate, which looks like this before the patch:
http://thewinecellarbook.com/amaraTemp/xpath.util_fun.html#xpath.util.simple_evaluate

after it - hope no one minds if I do it as an image, don't want to versions of the doc on my site and it takes a long time to upload as we have slow ADSL here in the French country side.



2. In xslt.exslt.regular_expressions:
http://thewinecellarbook.com/amaraTemp/xslt.exslt.regular_expressions_fun.html#xslt.exslt.regular_expressions.test_function

and after the patch:


If you haven't worked with .rst you have to watch out for some things, e.g.:
- indentation, e.g. multi line "param" have to be indented by at least one character I normally use more then one, the same for the table for the flags.
- note the "::" to mark the following block as source, green under lined in the first sample

I am probably preaching to experts, so ignore all this if you already know Sphinx/.rst.

Werner

[Luis Miguel Morillas]

El día 24 de abril de 2012 14:34, Sylvain Hellegouarch <s...@defuze.org> escribió:
>>
>>>
>>> As a side note, I can't remember if Amara is using BitBucket or GitHub?
>>> They would clearly provide greater visibility and make it easy to
>>> participate here and there IMO. Even for ths docs.
>>
>> https://github.com/zepheira/amara
>>
>
> Damn. The sad thing is that I'm actually subscribed to it as well. sigh.

Well, I'm more optimistic. I think that we've got good docs and good
examples at our wiki and at the great amara based projects (most of
them at zepheira repositories). Sure we do need to improve
organization and visibility of our docs. If you like Sphinkx we can
convert docs with some kind of moin2rst tool. i can work on it this
month.

-- luismiguel

> --
> - Sylvain
> http://www.defuze.org
> http://twitter.com/lawouach
>

[Werner]

Hi,

The last .zip with the build stuff incluced a config.py with a change I
started for the noindex stuff, which shouldn't have been in there.

Attached is the correct one.

Werner

[Werner]

Hi,

I need some input to be able to proceed with the Sphinx doc.

Since including the "C" modules I get a lot of "Duplicate object", e.g.:

<autodoc>:0: WARNING: duplicate object description of
amara._expat.SaxReader, other instance in
h:\devProjectsT\SphinxDocs\Amara2\source\amara._expat.SaxReader.rst, use
:noindex: for one of them

Is it expected/normal to have the SaxReader class defined in two places,
one in the above and the other in amara._expat.create_parser?

If yes, I assume I should add the Sphinx "noindex" to the create_parser one.

Werner

BTW, I made another change to the .rst generator do pick up things like
tree.node.xml_write, in the past it only picked up inspect.ismethod, I
changed it so that if that fails it checks for
inspect.ismethoddescriptor and if its name does not start with "__" it
is also included. The amaraTemp doc on my site is updated, will create
another zip of the generator etc when I fixed the above in one way or
the other.

[Werner]

Attached the latest config and .rst generator.

- Changed so that classes which generate duplicate object are only
generated once (hopefully I picked the correct one to suppress - see
config.py)
- some classes would cause an problem with Inheritance diags, suppresses
the generation of the diag for those

At this point there are only documentation string issues.

Werner

P.S.
How should one submit documentation patches, just send them to the list
here?

[Luis Miguel Morillas]

2012/4/29 Werner <werner...@sfr.fr>:

I think that could create a fork from the main github repo[1], make
changes and send a bundle of them to Uche, so Uche could unbundle and
submit them to the main repo. This is the way we worked with mercurial
before.

[1] https://github.com/zepheira/amara

Regards,

-- lm