Re: [Docutils-users] nested field lists in custom directives

[David G. <go...@py...>]

On Tue, Sep 26, 2017 at 5:28 AM, Robin Shannon <rj...@ro...> wrote:
> On 26 September 2017 at 06:45, David Goodger <go...@py...> wrote:
>>
>>
>> First, do you really need to implement a directive? You could just
>> embed the HTML in your reST source (``.. raw:: html``). It may be a
>> heck of a lot easier.
>
>
> Sage advice, but yes I do. Partly as a challenge to get my head around how
> classes work, and partly because it is a frequently requested feature in
> hovercraft (an html presentation generator).
>
>>
>> In your use case, do you want to allow multiple <track> elements
>> inside <video>? Multiple <source> elements? The HTML standard allows
>> multiples: videos in different formats, subtitles and captions in
>> different languages, etc. If the answer to either of these is "yes",
>> then you'll need something more robust.
>
>
> yes
>
>>
>> The only real *options* you'd have in this directive are "autoplay"
>> and "controls". And since they are simply flags (boolean attributes),
>> just include one to indicate "on" or exclude it to indicate "off";
>> don't use "true" and "false" values. See the "contents" directive
>> attribute "local" for an example.
>
>
> Thanks for pointing that out, that's a much better idea.
>
>>
>> The "track"-related data aren't options, they're content. If you have
>> a track, you must include certain attributes for it to make sense.
>> Then you have "required options", which is a contradiction in terms.
>> Bad smell, don't do that. And you can have multiple tracks, but it
>> doesn't generally make sense to repeat options. If you can standardize
>> the exact attributes you'll need (i.e. no variation), you can
>> implement these as a bullet list (one item per track) with positional
>> parameters (kind, language, source)::
>>
>>     * subtitles en foo.vtt
>
>
>
> Again, a much better idea.
> So, poking around in some of the other directives, it looks like the list
> items would be available to the directive as self.content and I would then
> split them by newlines. Or is there some other better way to get them
> already parsed as individual list items?

Do NOT split by newlines. Your directive lives inside a parser: use
the parser instead. You should do a recursive parse on the directive
content. See, for example, the list-table directive (class
docutils.parsers.rst.directives.tables.ListTable).

> Sorry, I appreciate that docutils
> is very well documented, but it is still quite confusing for a python
> neophyte.

Docutils is not comprehensively documented. A lot of the time the
answer will be, "Look at existing, similar examples," followed by,
"Use the Source, Luke!"

>> For example, allowing for multiple sources in the directive arguments,
>>     .. video:: foo.mp4 foo.webm foo.ogg
>
>
> Yep, that's how I've got it already. At least I had one good idea :) Is
> there some way of setting the optional_arguments parameter to unlimited or
> do I just set that to 10 safe in the knowledge that it would be a really
> strange use case that would need more than 11 different sources. It just
> seems slightly inelegant.

optional_arguments could have been defined as "-1 is equivalent to
infinity" (or some other sentinel value), but it wasn't. In cases like
this, when you want to have an unlimited number, the standard idiom is
to use sys.maxint, a very large number that is close enough to
infinity for our purposes.

> Thank you for your advice. It's very helpful.

You're welcome.

David Goodger
<http://python.net/~goodger>