Add a directives for general purpose documentation in downstream proj…

[swrichards]

Example of the HTML output at https://github.com/maykinmedia/django-setup-configuration/pull/57/files#diff-3400de187b7c71517c4599f1ff9b2f4fd011921adbcdbb999e681d134e4c8438 but here's what it looks like in OIP:

[swrichards]

@stevenbal @Coperh the tests don't yet pass but mainly because I mocking out a function in CI is rather tricky due to the convoluted import sequence, trying to fix that now but it won't change the core of the PR, so I am tagging you now for feedback.

[Coperh]

One thing is that I don't think it includes the templates in the release or at least when I install from github, they are missing. I do get the usage directive though

[swrichards]

One thing is that I don't think it includes the templates in the release or at least when I install from github, they are missing. I do get the usage directive though

This is a good point. I was using it locally as an editable install which did copy over the whole thing, but for setuptools it'll probably require a nudge to include the templates in the package. (In the meantime, it is testable with pip install -e, or should be)

[Coperh]

I think generally it looks good.

I would like the ability to change the template so I can add custom intro paragraph and remove the autoclass since that is not useful for CI/CD users

[Coperh]

Would be nice to override these templates. Not sure if I can now

[swrichards]

@Coperh I see a few options:

1. As you say, making the templates overridable. This has the drawback that Sphinx is really quite picky in building up the RST nodes (e.g. if you were to add headings or other directives, it might fail).
2. Add some arguments to this directive, for instance: to include/exclude the usage info, and to add a "style" enum for the headings (which could either be the verbose_title, the autodac tag to the step class as now, or a combination of both
3. Add some additional directives which adds more composability: so the usage text, TOC, and step sections are each their own directives which could be used separately to mix-and-match, with this directive being effectively a bundle of these separate directives.

I am inclined to do that refactoring in a subsequent PR, unless there's an obvious path to 1. we can add here.

[Coperh]

OR perhaps I could just override the _TEMPLATES_PATH?

[Coperh]

I wonder if you can render the step template and add it here?

[Coperh]

This node thing is confusing TBH

[swrichards]

I couldn't get this to work with just inserting the RST output directly. Because you don't know where the directive will be inserted into the final tree, it seems you have to go down this route to explicitly say you want a section with a certain title and so forth (if you do that in RST, the parser will end up complaining about "unexpected title sections" and such things).

[swrichards]

@stevenbal @Coperh I have added a few options to customize what sections are included/excluded (See the docs and test examples).