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?

[swrichards]

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

[stevenbal]

Looks good overall, some minor remarks

[stevenbal]

@swrichards something else I ran into just now: it might be useful to add anchors to the steps, that way you can still reference specific steps from other pages

.. _setup_configuration_Baz:

.. setup-config-example:: foo.bar.Baz

not entirely sure what the name of the reference should be though

[swrichards]

I have now rewritten this so the step sections are always RST sections, which mean they will always have an anchor id, which I've changed to ref-step-{full_step_module_path} for easier linking.

[stevenbal]

I think the only way to cross-reference is by adding an explicit reference like .. _ref-config-step-...: unfortunately 😬 (https://www.sphinx-doc.org/en/master/usage/referencing.html#cross-referencing-arbitrary-locations)

I tried linking to this another way, the only thing that seems to work is spelling out the path of the file + the anchor (https://github.com/open-zaak/open-notificaties/pull/228/files#diff-056134d467e07b8255b1205455315b00fd959de8fe75ce378dc3b0698587c7a8L82), but that reference isn't validated when building the docs, so that link would break if the path/anchor change and you wouldn't be notified about it by a failing build

[Coperh]

"""
    Config for ``ObjectType`` model from objecttypes-api
"""

Also does accept rst formatting which is nice

[Coperh]

Tests seem fine and the output looks correct to me.

[stevenbal]

Only remaining comment about references to steps, looks good otherwise

[stevenbal]

I think the only way to cross-reference is by adding an explicit reference like .. _ref-config-step-...: unfortunately 😬 (https://www.sphinx-doc.org/en/master/usage/referencing.html#cross-referencing-arbitrary-locations)

I tried linking to this another way, the only thing that seems to work is spelling out the path of the file + the anchor (https://github.com/open-zaak/open-notificaties/pull/228/files#diff-056134d467e07b8255b1205455315b00fd959de8fe75ce378dc3b0698587c7a8L82), but that reference isn't validated when building the docs, so that link would break if the path/anchor change and you wouldn't be notified about it by a failing build

[stevenbal]

for my understanding: how are these generated and how do you verify if they are correct?

[swrichards]

The HTML is read from the Sphinx output (from disk), I then use bs4 to extract the body (to avoid having to compare ephemeral and potentially dynamic values in the head/footer) and passed through approvaltests for verification. The latter gives better diffs and makes it easier to re-record the dumps if they change.

Whether they're correct: by visual inspection basically (as you would with say a Storybook snapshot).