Support the generation of meta model and API documentation

[stefanq]

Hello,

PyEcore provides a very easy way to expose arbitrary meta models given as one or more Ecore resources as a Python extension module.
Two of the more popular Python documentation generators are pdoc and Sphinx.
These dynamically evaluate the structure of Python modules, classes, methods and the contents of the __doc__ attribute for the purpose of generating cross linked documentation in HTML, PDF and other formats.
However, due to the way PyEcore works it is not possible to have generated API documentation by means of such documentation generators for the classes of such meta models which is a major drawback.

Requirements to support such documentation for an Ecore meta model would be

1. A mechanism is required which lets parsers like pdoc "see" the actual EPackage, EClass, EStructuralFeature and finally EOperation elements of the meta model (instead of the PyEcore meta class and related elements).
2. It would be important, if resulting __doc__ strings of EStructuralFeatures would implicitly contain a section documenting their common EMF properties like Default Value Literal, Multiplicity and the flags Ordered, Transient, Unique and Unsettable.
3. Documentation elements in the Ecore given as GenModel EAnnotations as specified in [1] chapter 9.8.1 are parsed into corresponding __doc__ attributes of Python entities.
4. In case any docstrings shall alternatively be implemented in the Python sources of the extension modules, a mechanism is needed to do so, e.g. by iterating over constituent elements of a DynamicEPackage and assigning __doc__.

[1] Dave Steinberg et.al. "EMF Eclipse Modeling Framework Second Edition"

[aranega]

@stefanq Thanks for your issue, you're right, PyEcore would really benefit from being able to be "understandable" by projects that generates code. At the moment, pyecoregen generates code for genmodel annotations, but only for class and methods.

I will try to investigate how to, either specialize "pydoc" in a way or another, or to allign as much as possible some mechanizm so it automatically understands how to deal with EClasses/EPackages ...