Maya's MEL language and Sphinx?

[YKdvd]

We use Autodesk's Maya 3D software, which embeds Python as a scripting language, and I have a sphinx setup to create some docs for that.  But Maya also has an older, TCL-based scripting language called MEL which is used for a lot of our codebase, and it would be nice to somehow pull some documentation out of that as well.  I was looking at the autodoc and sphinx-js extensions code, and was wondering if I could do a fairly quick and dirty extension that might help out?

I haven't dug into all the details, but is this a reasonable high-level idea of what an extension might do?  It would register a domain, say "mel:", and my .rst source file would use a directive like ".. mel:automelfile:: some_mel_filename".  My extension would implement a subclass of SphinxDirective for this, and its run() method would return "a list of nodes".  I'd be responsible for finding and parsing the MEL file, but if I could extract various blocks of text in Google docstring format (we use the Napoleon extension for our Python autodocs), there would be sphinx functions to turn them into py:module or py:function nodes or whatnot for my run() method to return, similar to what autodoc is presumably doing?

I wouldn't do anything fancy for the parsing, probably just some regular expression stuff to try and get a top-level comment and the ones associated with global procedures, but am I on the right track as to the design of an extension like this?

[Komiya Takeshi]

Hi,

Yes, your understanding is correct. autodoc reads a python script and
generates reST code containing "py:*" directives. After that,
generated code are parsed by nested_parse()
I hope source code of AutoDirective class will help you.
https://github.com/sphinx-doc/sphinx/blob/7faeb793e2e16cde4e5759443fb7f84efddcd9ea/sphinx/ext/autodoc/directive.py#L109-L158

Thanks,
Takeshi KOMIYA

2019年10月12日(土) 3:03 YKdvd <david...@gmail.com>:

>
> We use Autodesk's Maya 3D software, which embeds Python as a scripting language, and I have a sphinx setup to create some docs for that. But Maya also has an older, TCL-based scripting language called MEL which is used for a lot of our codebase, and it would be nice to somehow pull some documentation out of that as well. I was looking at the autodoc and sphinx-js extensions code, and was wondering if I could do a fairly quick and dirty extension that might help out?
>
> I haven't dug into all the details, but is this a reasonable high-level idea of what an extension might do? It would register a domain, say "mel:", and my .rst source file would use a directive like ".. mel:automelfile:: some_mel_filename". My extension would implement a subclass of SphinxDirective for this, and its run() method would return "a list of nodes". I'd be responsible for finding and parsing the MEL file, but if I could extract various blocks of text in Google docstring format (we use the Napoleon extension for our Python autodocs), there would be sphinx functions to turn them into py:module or py:function nodes or whatnot for my run() method to return, similar to what autodoc is presumably doing?
>
> I wouldn't do anything fancy for the parsing, probably just some regular expression stuff to try and get a top-level comment and the ones associated with global procedures, but am I on the right track as to the design of an extension like this?
>

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/3dbf618a-2e36-460e-a724-24989b8f8687%40googlegroups.com.

[YKdvd]

I've got a rudimentary version of this working- my domain and directive's run() is returning the node children results of parsing some MEL text I pull out of a source file, something like autodoc does.  I was wondering if there is anything it could return to create RST source that would be processed into multiple output files?  So a directive is in "source.rst" and run() provides content for "source.html", but I'd like to be able to have it generate "source2.html", "source3.html" as well.  For instance, the directive might create an output file for each procedure it discovers, rather than accumulating them all in the current output.

> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx...@googlegroups.com.

[Komiya Takeshi]

It is hard to generate new document from directive. To do that, you
need to hack Sphinx core deeply. Indeed, you can do it by extensions.
For example, autosummary extension parses reSturcturedText by itself
and generate stub files before reading document. But it is very hacky
and difficult way to implement it.

Thanks,
Takeshi KOMIYA

2019年12月22日(日) 10:08 YKdvd <david...@gmail.com>:

> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/8144f58c-483a-4e83-bcc6-6415f999f693%40googlegroups.com.

[YKdvd]

I'll probably do something standalone before sphinx to build the additional rst files.

One more thing, the "napoleon" extension doesn't seem to give any examples where the short or longer comment inside the docstring has multiple lines:

"""Short description
Longer description goes across multiple lines.
Like this.
And also like this.
... <more docstring:
"""

Napoleon seems to turn this into:

Short description

 

Longer description goes across multiple lines. Like this. And also like this.

Napoleon isn't designed to honor the linebreaks in the longer part of the description, and it gets treated like RST text and flowed together?  You'd have to put something like "|" on the lines in the doctring to get linebreaks?  Or am I missing a napoleon setting?

> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/8144f58c-483a-4e83-bcc6-6415f999f693%40googlegroups.com.

[YKdvd]

There's a blank line between "Short description" and "Longer description..." in the docstring (got removed by the forum formatting).