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

[Robin S. <rj...@ro...>]

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? Sorry, I appreciate that docutils
is very well documented, but it is still quite confusing for a python
neophyte.

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.

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

Peace,
Robin.