Generate binding classes with docstrings

[camille83]

Hello,

In order to use an automated tool for API documentation generation (e.g. Sphinx), I would like to generate binding classes with docstrings. The docstrings should correspond to the documentation of the xml schema.

As an example, pyxb binding applied to the following xml schema :

<?xml version="1.0" encoding="utf-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:simpleType name="PositiveFloat">
    <xsd:annotation>
        <xsd:documentation xml:lang="en">
        Positive float type.
        </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:float">
        <xsd:minExclusive value="0"/>
    </xsd:restriction>
    </xsd:simpleType>
    <xsd:element name="myPositiveFloat" type="PositiveFloat">
        <xsd:annotation>
            <xsd:documentation xml:lang="en">
                This is my positive float.
            </xsd:documentation>
        </xsd:annotation>
    </xsd:element>
</xsd:schema>

should generate a python module like :

(...)
class PositiveFloat(...)
    '''
    Positive float type.
    '''
    (...)
(...)
'''This is my positive float.'''
myFixed = pyxb.binding.basis.element(...)
(...)

Do you think pyxb permits this ?

Thank you in advance.

Camille

[Peter A. Bigot]

It already does this for the complex type PositiveFloat.  You can do:
{{{
import test
help(test.PositiveFloat)
i = test.myPositiveFloat(4)
help(i)
}}}
and see the documentation.  Documentation should also be applied to elements in complex types, and several other documentable things.

Documentation on elements is currently lost, because elements are instances of a PyXB class rather than classes themselves, so their docstrings come from the pyxb.binding.basis.element class.  The annotation could be added to the generated code, and that might not be a bad idea, but they would not be available at runtime like annotations for types.

Peter

[camille83]

Thanks. It only remains me to create an element by type.

[camille83]

I have said "It only remains me to create an element by type", but it would have been more correct to say : "It only remains me to create a type for each element to be documented".

[Peter A. Bigot]

Thanks; that makes much more sense.

If your schema style uses anonymous complex types within the content of the element declaration, you can put the annotations in those types rather than move the types out to be named types at the top level (though moving them out makes a more re-usable schema).

It would make sense for PyXB to detect this case and copy the documentation from the element to an undocumented anonymous type.  I've added https://sourceforge.net/apps/trac/pyxb/ticket/79 so this should happen with the next release.

[camille83]

Great ! Thanks !