There's a blank line between "Short description" and "Longer description..." in the docstring (got removed by the forum formatting).
On Sunday, December 29, 2019 at 10:46:22 PM UTC-4, YKdvd wrote: > > 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? > > On Sunday, December 22, 2019 at 7:24:19 AM UTC-4, Komiya Takeshi wrote: >> >> 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 <[email protected]>: >> > >> > 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. >> > >> > On Friday, October 11, 2019 at 11:21:59 PM UTC-3, Komiya Takeshi wrote: >> >> >> >> 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 <[email protected]>: >> >> > >> >> > 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 [email protected]. >> >> > To view this discussion on the web visit >> https://groups.google.com/d/msgid/sphinx-users/3dbf618a-2e36-460e-a724-24989b8f8687%40googlegroups.com. >> >> >> > >> > -- >> > 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 [email protected]. >> > To view this discussion on the web visit >> https://groups.google.com/d/msgid/sphinx-users/8144f58c-483a-4e83-bcc6-6415f999f693%40googlegroups.com. >> >> >> > -- 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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/87ddbdf2-64e5-4ba7-b6cc-f684beda399a%40googlegroups.com.
