This ticket had assigned some Differential requests:
D93

Aside from the legal discussion regarding GPLv3 code - everything is working and ready to go for this fix. We just need to update the content in the directives themselves, afaict.

Per the meeting today:

reST can be place in:

• short_description
• description
• author
• notes
• requirements

Which means the only places you can't put reST is: the version and options. Also, the EXAMPLES - but that's meant to be code examples, so having reST there doesn't make a ton of sense anyway, IMO.

OK, here's an alternative proposal:

Instead of yaml blocks with a specific structure, it uses rst/sphinx in a docstring, the same way we do it for all other documentation. The upside is that we can use full rst/sphinx capabilities easily (the same way as everywhere else). It's not a "new language". The downside is that there is no common template definition, so we can't alter the directive appearance in a central place - we would have to adjust all our files to achieve that. (If there is a strong desire for a template-like behavior, it might be better to look at sphinx/rst templating tools rather than using custom yaml processing for that).

In the first example, a module docstring is used:
http://kparal.fedorapeople.org/taskotron/#142/html/directives.html

In this case, we can't use sphinx info fields, we use custom sections and custom parameter markup.

In the second example, a class docstring is used:
http://kparal.fedorapeople.org/taskotron/#142/html/directives2.html

In this case, we use info fields, but OTOH it seems that we can't use custom section headers, because Sphinx ignores them. Also, the class definition is displayed as the first line, not sure if we can get rid of that.

For comparison, this is the ansible+yaml output:
http://kparal.fedorapeople.org/taskotron/#142/html/koji_directive_module.html

For all examples, the html was generated from F2839.

I think that the pure rst/sphinx documentation is closer to the KISS principle, it uses the same syntax we already know, without jumping over any hurdles. It's also not restrictive, you can you markup in option description, you can use markup in examples. But the output might not be as consistent as with ansible script + yaml approach. It depends on what we want more.

(Btw, there is some support for substitutions in rst, which could be used at least partly to keep specific sections of the directives documentation exactly the same).

Looking at the "yaml" examples (both rendered and given in the description):
# Is there a way to set returns section
# Is there a way to add formating to the options' default/description?
# Is there a way to add formatting to the Examples section? I know that:

! In #142#11, @roshi wrote:
Also, the EXAMPLES - but that's meant to be code examples, so having reST there doesn't make a ton of sense anyway, IMO.

But that is IMHO false premise - examples that are "just code" are far less useful than commented examples explaining what the code means. Also creating several examples (i.e. several sub-sections in the examples section) is IMHO really useful, and making a lot of sense.

Also (but this is just my personal opinion) - if the documentation is present in the source file, then it should be reasonably readable (if not well readable, which would be my preference) and understandable in the "unrendered" state. Using weird hacks for sake of making the rendered form "nice" is IMHO not the right approach.

! In #142#16, @jskladan wrote:
Looking at the "yaml" examples (both rendered and given in the description):
# Is there a way to set returns section
# Is there a way to add formating to the options' default/description?
# Is there a way to add formatting to the Examples section? I know that:

! In #142#11, @roshi wrote:
Also, the EXAMPLES - but that's meant to be code examples, so having reST there doesn't make a ton of sense anyway, IMO.

But that is IMHO false premise - examples that are "just code" are far less useful than commented examples explaining what the code means. Also creating several examples (i.e. several sub-sections in the examples section) is IMHO really useful, and making a lot of sense.

@roshi is working to add those things to the yaml docs and I expect that to be done today. I wrote a 23 line patch (20 of which were deletion) that adds a blank line between desc elements and interprets the examples as pure reST to make example docs [[http://tflink.fedorapeople.org/taskotron/demo-directive-docs/koji_directive_module.html|more like what I think you and @kparal are looking for]].

That linked example is

EXAMPLES = """
This is an example::

  - name: do something
    koji:
      action: download
      envr: foo-1.0-2.fc99

This is another example::

  - name: download tag
    koji:
      action: download_tag
      tag: f99-updates-testing-pending

"""

Also (but this is just my personal opinion) - if the documentation is present in the source file, then it should be reasonably readable (if not well readable, which would be my preference) and understandable in the "unrendered" state. Using weird hacks for sake of making the rendered form "nice" is IMHO not the right approach.

I still don't get how they aren't reasonably readable, the yaml-ish style docs are a little different but I find them readable enough.

If we were talking about library code, then I'd agree that this isn't the right way to document things. However, we're not talking about library code - we're talking about user-facing docs for the building blocks of tasks. Directives should generally not be imported by other code and only used in tasks. As I see it, the priorities for the directive documentation are:

contain the information needed for users to write tasks

readable and easily understandable in their rendered, user-facing form

as consistent as possible with other directive docs in their rendered form, even if that means restricting their content

easy for directive authors to understand the format and write consistent docs that are unlikely to need changes in review

If we have those things and keep the docs reasonably readable in source form (which, while not as good as other doc forms, I think the yamlish docs are //reasonably// readable), that's what we're looking for. The examples I've seen of pure reST and sphinx reST directive docs are not easy enough to understand in rendered form to use. We could have manual enforcing of some format for the directive docs or hack at reST parsing to make reST commands to do what we want but we'd be in a similar place with more work to do and/or more easily introduced human error.

There are concerns about the yamlish format not being flexible enough. Keeping with koji_directive as an example, I agree that a simple "required = yes/no" is not enough but I disagree that this is an indication we should choose a different documentation formation. I think that's an argument that we should look at how the directives are written: if they can't be described in a paragraph or two and a simple table of parameters, maybe their interface is too complex. For the koji_directive case, I think this is an argument for splitting that up into two different directives download_build and download_tag - that makes the usage of the directives more clear, the arguments cleaner and the docs more easily understood without too much effort.

easy for directive authors to understand the format and write consistent docs that are unlikely to need changes in review

I think the current system fails this. It's not rst, it's not yaml, it's rst in yaml and with some custom exceptions. I can't imagine how we're going to reasonably describe the format that can be used to the directive authors.

(Btw, we seem to talk about directive authors like they were someone else than us. Are we going to ship directives written from third-parties? Are we going to support them? Or will we allow to plug in directives from the task directory? I am confused.)

However, if we're going to rewrite the ansible script (which I wanted to avoid, I don't consider it cost effective), I believe the following should be changed:
EXAMPLES as a proper rst text (already done, thanks @tflink)
description as a proper rst text (I don't really understand why it is a list of strings)
option description as a proper rst text
option default value as a proper rst text
notes and requirements appended to synopsis section (it seems weird to append notes to examples and requirements to options), or they should have a separate section.
the TOC removed (since the assumption is that directives should be short and simple)
* and of course, new sections for //returns// and //raises//

! In #142#18, @kparal wrote:
easy for directive authors to understand the format and write consistent docs that are unlikely to need changes in review

I think the current system fails this. It's not rst, it's not yaml, it's rst in yaml and with some custom exceptions. I can't imagine how we're going to reasonably describe the format that can be used to the directive authors.

You fill in blanks, I'm not sure what's so hard about doing that or describing that.

(Btw, we seem to talk about directive authors like they were someone else than us. Are we going to ship directives written from third-parties? Are we going to support them? Or will we allow to plug in directives from the task directory? I am confused.)

I figure that we may end up accepting patches from folks who are not currently involved in Taskotron work but even if that wasn't the case, I don't think it's all that easy to get consistent output. If we leave the documentation format flexible, we're going to end up with small variations between the different directives.

However, if we're going to rewrite the ansible script (which I wanted to avoid, I don't consider it cost effective), I believe the following should be changed:

This may be where the impasse lies - I think that more free-form documentation is going to be far less cost effective in the long run. I want the format for directive documentation to be on the restrictive side because it forces us to be succinct and can expose logical inconsistencies in how the directives work.

• EXAMPLES as a proper rst text (already done, thanks @tflink)
• description as a proper rst text (I don't really understand why it is a list of strings)

I still don't understand why plain text doesn't work for the description but it doesn't matter to me enough to fight you on this. Plain reST is fine.

• option description as a proper rst text
• option default value as a proper rst text

These are a lot more difficult than it may appear. That table is too complicated to do reasonably in reST, so it ends up being rendered as raw HTML. We'd have to hack in rst to html conversion in order to make these work.

I can kinda see the rationale for wanting markup in other parts of the docs, but in this case - all of the inputs need to be in plain text. What use case is there for full markup in this part of the docs?

• notes and requirements appended to synopsis section (it seems weird to append notes to examples and requirements to options), or they should have a separate section.

I think it makes sense to leave the reqirements appended to the options section but moving the notes is fine by me.

• the TOC removed (since the assumption is that directives should be short and simple)

agreed, I don't like that TOC either - it's just wasted space.

• and of course, new sections for //returns// and //raises//

The returns part was never in doubt - the code in D93 is a proof-of-concept example. I told @roshi to put the least amount of effort possible into that code until we got farther on licensing and format.

I fail to see any reason to put the exceptions section in the directive docs since users can't do anything about raised exceptions but I'm not going to fight you on it since it doesn't hurt anything - just makes the docs longer than they need to be. The exceptions that bubble up to the user should be well-formed enough to be pretty much self-explanatory.

On a related note - we have about 1 week to get this figured out and all the content written if we want to have a chance of deploying production for f21 branch and leave time for testing. We can change minor stuff later (release early, release often) but we need to have some decent directive docs.

I want to have the majority of the format discussion done tomorrow so we can focus on content and get everything done by the end of the iteration.

I've updated how directive doc pages get rendered. You can see an example [[ http://roshi.fedorapeople.org/koji_directive_module.html | here ]].

@kparal and I will be working on finishing this out on the [[https://bitbucket.org/fedoraqa/libtaskotron/branch/#142-directivedocs | #142-directivedocs branch]].

I fail to see any reason to put the exceptions section in the directive docs since users can't do anything about raised exceptions but I'm not going to fight you on it since it doesn't hurt anything - just makes the docs longer than they need to be. The exceptions that bubble up to the user should be well-formed enough to be pretty much self-explanatory.

It's true that documenting exceptions is more useful for us than for the user (even though sometimes the user can also be interested to know when exactly the directive - and thus the whole task - ends with error). But I think it's better to put it directly into DOCUMENTATION than to create yet another separate documentation string (either as a docstring, or as a DEVDOC variable, or something similar). But I don't have a strong opinion on this either.

option description as a proper rst text
option default value as a proper rst text

These are a lot more difficult than it may appear. That table is too complicated to do reasonably in reST, so it ends up being rendered as raw HTML. We'd have to hack in rst to html conversion in order to make these work.

I can kinda see the rationale for wanting markup in other parts of the docs, but in this case - all of the inputs need to be in plain text. What use case is there for full markup in this part of the docs?

If you look at our API docs, I like to graphically distinguish values or references from other text. I find that much more readable. But if it's hard to do, then we'll need to stay with plaintext for the moment, and possibly improve that in the future.

! In #142#19, @tflink wrote:
You fill in blanks, I'm not sure what's so hard about doing that or describing that.

That in order to do any formating, you need to know what kind of markup you can use in that particular "blank" (or what hacks you need to use in order to be able to use some [maybe specific] markup). It is not consistent through the "blanks", and so it is no "easy".

<snip>... we're going to end up with small variations between the different directives.

I do not understand why small variations would be that big of a deal, since the (rendered) documentation is not meant to be machine parseable, and I guess we won't be accepting anything that is largely different (from what our "template" will be in the moment) anyway.

<snip>... I think that more free-form documentation is going to be far less cost effective in the long run.

Why exactly?

I want the format for directive documentation to be on the restrictive side because it forces us to be succinct and can expose logical inconsistencies in how the directives work.

Can you provide some examples of the (possible) logical inconsistencies that would be exposed by using highly restrictive template for documentation? I do not really see any, but I might be missing some part of the picture. To be precise - I do not know how would the restrictive template for documentation catch problems like inconsistent input-arg names, or misleading return values. But I guess that you have something else on your mind, so I'd like to be able to evaluate the right pros and cons.

• option description as a proper rst text
• option default value as a proper rst text

These are a lot more difficult than it may appear. That table is too complicated to do reasonably in reST, so it ends up being rendered as raw HTML. We'd have to hack in rst to html conversion in order to make these work.

I can kinda see the rationale for wanting markup in other parts of the docs, but in this case - all of the inputs need to be in plain text. What use case is there for full markup in this part of the docs?

Although I can probably live with description being something like: Accepted values are None, "foo", "bar" or "moo".
I fel that something like this is far more readable: Accepted values are None, "foo", "bar" or "moo".

I'm not saying that I need to have numbered lists and all the fancy stuff, but basic inline markup is IMHO quite reasonable requirement.

! In #142#17, @tflink wrote:

@roshi is working to add those things to the yaml docs and I expect that to be done today. I wrote a 23 line patch (20 of which were deletion) that adds a blank line between desc elements and interprets the examples as pure reST to make example docs [[http://tflink.fedorapeople.org/taskotron/demo-directive-docs/koji_directive_module.html|more like what I think you and @kparal are looking for]].

Cool!

Also (but this is just my personal opinion) - if the documentation is present in the source file, then it should be reasonably readable (if not well readable, which would be my preference) and understandable in the "unrendered" state. Using weird hacks for sake of making the rendered form "nice" is IMHO not the right approach.

I still don't get how they aren't reasonably readable, the yaml-ish style docs are a little different but I find them readable enough.

If this documentation is at the end of the file, and won't bother me, then I guess I do not have objections against it being in the files directly. I just do not understand why having two separate tools for rendering documentation is a sane thing. Especially since the "other" tool (the yaml-ish renderer) is somehing we need to patch anyway in order to be relevant.

If we were talking about library code, then I'd agree that this isn't the right way to document things. However, we're not talking about library code - we're talking about user-facing docs for the building blocks of tasks. Directives should generally not be imported by other code and only used in tasks. As I see it, the priorities for the directive documentation are:

contain the information needed for users to write tasks

readable and easily understandable in their rendered, user-facing form

Both the yaml-ish style and rst/sphinx style pass these, IMHO, so it is not an argument for either of those

as consistent as possible with other directive docs in their rendered form, even if that means restricting their content

What are the "other directive docs"? Is it the rst/spinx generated documentation? If so, why wouldn't this be an argument favouring rst/sphinx?

easy for directive authors to understand the format and write consistent docs that are unlikely to need changes in review

This I can not really argue about, "filling the blanks" in rst/sphinx template is the same as filling the blanks in the yaml-ish style docs.

<snip>The examples I've seen of pure reST and sphinx reST directive docs are not easy enough to understand in rendered form to use.

Why? What do you think is hard to understand?

There are concerns about the yamlish format not being flexible enough. Keeping with koji_directive as an example, I agree that a simple "required = yes/no" is not enough but I disagree that this is an indication we should choose a different documentation formation. I think that's an argument that we should look at how the directives are written: if they can't be described in a paragraph or two and a simple table of parameters, maybe their interface is too complex. For the koji_directive case, I think this is an argument for splitting that up into two different directives download_build and download_tag - that makes the usage of the directives more clear, the arguments cleaner and the docs more easily understood without too much effort.

Although I can somewhat relate, this feels like warping the code for the sake of "easy docs writing". I can see the benefits of writing code differently for it to be testable, but I really can not see a point of having the code driven by the limits of documentation tool.

Anyways, since we are on such a tight schedule, I do not really feel the need to be a roadblock, so if there is a strong will to go with the yaml-ish style docs, I'm not going to fight it.

All my reservations are related to the problems and disabilities of this particular conversion script. As I said initially, I'm OK with this approach in general. So my main requirement is that the script works correctly. Currently, it's way too easy to break the docs generation:

options:
   option_name:
       description:
           - Having an empty line 

             inside the string breaks the template.

or

options:
   option_name:
       description:
           - Having a colon: inside the text breaks the template. Wheee.

Also, it's not possible to force a line break. That's even less than //plain text//.

We will likely need to overhaul the script a lot, which brings me back to my question whether it wouldn't be better to find a proper tool for these purposes (reST templating). In any way, if it works well and has reasonable level of features/restrictions, I'm satisfied. If we can't do it or are pressed hard by time, we should go with pure reST documentation and find a better doc generation tool once we have time for that.

options:
option_name:
description:
- Having a colon: inside the text breaks the template. Wheee.

I got caught into my own trap here. Of course, to have it as a proper YAML, you need to enclose the string in quotes if you want to have a colon inside. But it nicely illustrates the problems our directive writers will be fighting with. And what do you do if you need a colon //and// a quotation mark inside? I don't know. I just know it's way too complex.

In this particular example, it would help to get rid of the list of strings idea and make it a simple string. Then we would start it with |<newline> in the example and the escape problems would be hopefully gone.

(The first error example still applies, it's not fixed even with enclosing it into quotation marks.)

Just to be clear: I do see the potential of having the documentation provided in a kind of structure (say yaml), and I can see the potential benefits of it. Especially the fact that the structure can then be rendered in a template, which means that changing the way the documentation looks is a matter of changing one template file.

So if the reason for using it is that, I am all for it, and I can see why using "freeform" rst would be worse choice.

My objection is though, that there should be (ideally) next to none limits for (at least inline) formatting, and that the way Parameters are rendered needs to be changed.

The current Parameters table is really sparse, and structured illogically, thus being so hard/unpleasant to read. The current flow of information (not talking about typography, which is a bit different but not that separate issue) is parameter, required, default, choices, comments while the (IMHO) better way would be parameter, required, comments, default, choices Then you get the information in order that is more natural - why should I know all the possible choices before I'm even told what the parameter means? Also, the sparse columns then are at the end and are not breaking the flow of text.

This is then tied to typography. The way it is done now, there is no "line" the eye can follow while reading the text. Yes, there are the table borders, but since the table is sparse, and all the cells are vertically aligned to centre, reading it is really uncomfortable.

Should we keep the table appearance then I'd require these changes in order to make it readable and useable:
# capitalize the the table header's initial letters
# rename "comments" to "description"
# align vertically to top
# make the borders between cells very, very non-intrusive)
# remove the unnecessary padding/margin on the list items

Ideally also:
# assign classes to the s
# make the parameter names bold
# make he table header in italics (non-bold)

Most of this can be easily done using quite simple css. And I guess that the programatical changes required to change the order (and names) of colums would be quite easy. This would be the visual outcome I'd be happy with: http://jskladan.fedorapeople.org/table.html

! In #142#22, @jskladan wrote:

! In #142#19, @tflink wrote:
You fill in blanks, I'm not sure what's so hard about doing that or describing that.

That in order to do any formating, you need to know what kind of markup you can use in that particular "blank" (or what hacks you need to use in order to be able to use some [maybe specific] markup). It is not consistent through the "blanks", and so it is no "easy".

With the exception of the parameter lists and version numbers, it's pretty much sphinx-dialect reST embedded into yaml so that everything can be reformatted in a consistent way.

<snip>... we're going to end up with small variations between the different directives.

I do not understand why small variations would be that big of a deal, since the (rendered) documentation is not meant to be machine parseable, and I guess we won't be accepting anything that is largely different (from what our "template" will be in the moment) anyway.

It depends on the variation, I suppose but I agree that the world isn't going to stop if the docs started looking slightly different for two directives.

<snip>... I think that more free-form documentation is going to be far less cost effective in the long run.

Why exactly?

The cost of reviewing them to make sure that we have consistent visual style in the rendered docs, mostly. I think that making changes to the template or the information we want in the directive docs would be less expensive with the yamlish docs but that second part's debatable - the main part is with the reviews.

I want the format for directive documentation to be on the restrictive side because it forces us to be succinct and can expose logical inconsistencies in how the directives work.

Can you provide some examples of the (possible) logical inconsistencies that would be exposed by using highly restrictive template for documentation? I do not really see any, but I might be missing some part of the picture. To be precise - I do not know how would the restrictive template for documentation catch problems like inconsistent input-arg names, or misleading return values. But I guess that you have something else on your mind, so I'd like to be able to evaluate the right pros and cons.

koji_directive is an example. It can be used to download either a tag or a build but the required parameters change depending on what you feed into action. This makes the documentation a bit more difficult because most parameters aren't a clear yes/no for required.

I think this suggests that the koji_directive is a bit too complicated and should be split into koji_build and koji_tag directives so that the purpose of each directive is clear and simple.

• option description as a proper rst text
• option default value as a proper rst text

These are a lot more difficult than it may appear. That table is too complicated to do reasonably in reST, so it ends up being rendered as raw HTML. We'd have to hack in rst to html conversion in order to make these work.

I can kinda see the rationale for wanting markup in other parts of the docs, but in this case - all of the inputs need to be in plain text. What use case is there for full markup in this part of the docs?

Although I can probably live with description being something like: Accepted values are None, "foo", "bar" or "moo".
I fel that something like this is far more readable: Accepted values are None, "foo", "bar" or "moo".

I'm not saying that I need to have numbered lists and all the fancy stuff, but basic inline markup is IMHO quite reasonable requirement.

I'm not against having it but I'm not seeing a great way to actually do it. Given the choice between markup in the parameters table and having the table at all, I'd prefer to have the table - I think having the parameters in that format makes them much easier to understand because you don't need to read the whole thing to find out what the parameter names are, the default value etc.

One of the parts of this that I am rather attached to is the parameter table - I think that is much easier to parse, scan and read than the way sphinx renders parameters but I haven't been able to figure out a sane way to do that in reST. If someone can figure that out, there's much less of a reason to use the yamlish docs.

Also (but this is just my personal opinion) - if the documentation is present in the source file, then it should be reasonably readable (if not well readable, which would be my preference) and understandable in the "unrendered" state. Using weird hacks for sake of making the rendered form "nice" is IMHO not the right approach.

I still don't get how they aren't reasonably readable, the yaml-ish style docs are a little different but I find them readable enough.

If this documentation is at the end of the file, and won't bother me, then I guess I do not have objections against it being in the files directly. I just do not understand why having two separate tools for rendering documentation is a sane thing. Especially since the "other" tool (the yaml-ish renderer) is somehing we need to patch anyway in order to be relevant.

Sure, but the patches are relatively simple, AFAIK - mostly changing the template around.

If we were talking about library code, then I'd agree that this isn't the right way to document things. However, we're not talking about library code - we're talking about user-facing docs for the building blocks of tasks. Directives should generally not be imported by other code and only used in tasks. As I see it, the priorities for the directive documentation are:

contain the information needed for users to write tasks

readable and easily understandable in their rendered, user-facing form

Both the yaml-ish style and rst/sphinx style pass these, IMHO, so it is not an argument for either of those

This gets down to opinion, but I find the way that sphinx renders the parameters very difficult to read.

as consistent as possible with other directive docs in their rendered form, even if that means restricting their content

What are the "other directive docs"? Is it the rst/spinx generated documentation? If so, why wouldn't this be an argument favouring rst/sphinx?

A better way to phrase that would have been "documentation for other directives" - making the user-facing docs for all directives consistently formatted.

<snip>The examples I've seen of pure reST and sphinx reST directive docs are not easy enough to understand in rendered form to use.

Why? What do you think is hard to understand?

I find the parameter lists very dense and difficult to read. Part of this is the sphinx theme that we're using but it tends to put all the information that I would care about as a user in a sentence or paragraph form. I have to read the entire thing in order to get the information I need instead of being able to scan a table for parameter names and values - going on to the examples if there's something I don't quite understand.

There are concerns about the yamlish format not being flexible enough. Keeping with koji_directive as an example, I agree that a simple "required = yes/no" is not enough but I disagree that this is an indication we should choose a different documentation formation. I think that's an argument that we should look at how the directives are written: if they can't be described in a paragraph or two and a simple table of parameters, maybe their interface is too complex. For the koji_directive case, I think this is an argument for splitting that up into two different directives download_build and download_tag - that makes the usage of the directives more clear, the arguments cleaner and the docs more easily understood without too much effort.

Although I can somewhat relate, this feels like warping the code for the sake of "easy docs writing". I can see the benefits of writing code differently for it to be testable, but I really can not see a point of having the code driven by the limits of documentation tool.

If we were talking about library code or something other than directive docs, I'd agree with you. However, the way that directives are used in taskyaml is already really restrictive - far more so than the proposed documentation style. I think that keeping the directives simple is useful because it helps keep their usage easy to understand and use in tasks.

Wow, that comment was longer than I intended it to be. Somehow it didn't look quite so long in preview :-/

To make sure I'm clear - I'm not married to the specifics of what has been presented thus far. The two parts that I really want to see are:
the table format for parameters
a template for the directive docs so that non-content changes can be made in a single place

I'm flexible on pretty much the rest of the things (css for the table, the order of the columns, etc)

! In #142#20, @roshi wrote:
@kparal and I will be working on finishing this out on the [[https://bitbucket.org/fedoraqa/libtaskotron/branch/#142-directivedocs | #142-directivedocs branch]].

As a progress report, I've fixed the most critical bugs in the script. There are some still issues, but those are less important and I assume Mike will deal with them soon. We're somewhat behind on the content, so far only the koji_directive has been finished. But now that the template doesn't break when using peculiar characters like : or |, the speed should increase. I'll work on documenting more of the directives in the following week.

Mike, if you can, please make sure the whole script ends with a reasonably descriptive error message, if one of the mandatory documentation fields is either not present or is empty (module, short_description, description, returns, parameters.parameter_name.required, parameters.parameter_name.description, parameters.parameter_name.type) or filled with an incorrect value (parameters.parameter_name.required other than true or false). The whole script should exit with a non-zero exit code, it should not just report an error and continue - that would be too easy to overlook. Thanks.

I've updated the script with the requested error checks. It will sys.exit(1) if there's a formatting error. Much easier to see things go wrong now :)

I have documented all directives, but I was unable to check rendered docs for the last few of them, because the generator script got broken yesterday. Mike, can you please fix it quick?

$ make clean html
rm -rf build/*
rm -rf source/directives/*
python generate_directive_docs.py -t rst --template-dir=directives_template/ --module-dir=../libtaskotron/directives -o ../docs/source/directives && sphinx-build -b html -d build/doctrees   source build/html
Traceback (most recent call last):
  File "generate_directive_docs.py", line 408, in <module>
    main()
  File "generate_directive_docs.py", line 363, in main
    category_list_file = open(category_list_path, "w")
IOError: [Errno 2] No such file or directory: '../docs/source/directives/modules_by_category.rst'
make: *** [html] Error 1

Just FYI - branch feature/rst_in_params (based on the now acked D93) adds possibility to use rst also in the parameter fields, and adds custom CSS for the table, so it can be looked at without blood dripping from your eye sockets :)

D93 is closed - so closing this task as well.