[RFC] Firewall rules documentation

[ganto]

The past few days I was reading through the firewall rule templates and tried to write down a simple documentation about what I found. Maybe this can act as a starting ground for a better ferm rule template documentation (as requested in #57).

There are still some keys where I didn't figure out yet how exactly they are used. There also might be some that I misread...

If you want, I can make this ready to merge, but I need some input:

• content:
  • Please review the descriptions and point me to misunderstandings and mistakes. I'm not a native english speaker.
  • Please help to fill the gaps currently being marked with a ?
• ReStructured Text formatting:
  • How to properly cross-reference the variable documentation of the default variables? I guess the defaults.html#envvar-... is not really the correct way to do.
  • How to cross-reference other DebOps roles and their variable documentation? See the hint to libvirtd__ferm__dependent_rules for example.
  • How to make the templates a link-able subsection? Is it possible to somehow define a type as for envvar? Would be nice if they could be linked e.g. from the default variable documentation or future guides.
  • Is there a easy way to test-build the documentation? Or do I really need to setup the entire Read The Docs locally for this?

[drybjed]

First of all, thanks for the documentation! This looks excellent.

To test the documentation locally in case there are errors, I usually use a disposable LXC container and install python-sphinx in it, then build the documentation from https://github.com/debops/docs/ and check the results there. There's no need to setup entire RTFD, it's just the template, mostly.

Problem with cross-referencing documentation in other roles is that the documentation for each role is tested separately, and the entire docs are tested separately. Without documentation of other roles present, the cross-reference links would be broken and sphinx would emit an error. I suppose the best way would be to test the whole documentation with each role, which should be easy to do... I'll try to switch to that during the week, then doing cross-role references should work fine.

[drybjed]

Linking templates directly in RST documentation would most likely require some kind of conversion, as with yaml2rst, but after thinking about it I decited against it. Instead of including the documentation as a Jinja comment in the templates I have switched to writing better documentation, with examples in RST in the docs/ directory instead (see defaults-configuration.rst in many roles. When a role is more complicated than simple list of variables, I write multiple documents explaining each function in detail (see debops.pki).

[ganto]

Thanks a lot for your quick response. I'll try to update the documentation according to your feedback later tonight.

[ganto]

To test the documentation locally in case there are errors, I usually use a disposable LXC container and install python-sphinx in it, then build the documentation from https://github.com/debops/docs/ and check the results there.

Seems like a good idea. I followed your example and tried to build the current state of the PR.

However, at the places where I reference a variable from the defaults.rst with e.g. :ref:ferm__default_rules``, I get an warning like:

.../ansible-ferm/docs/rules.rst:20: WARNING: undefined label: ferm__default_rules (if the link has no caption the label must precede a section header)

Then the cross-link is not created. Any hints on this?

[ganto]

I think I made some progress with the formatting of the rules documentation tonight. Each rule template now has a separate subsection. I was also able to fix the variable references I was struggling with yesterday.

Now I'll try to fix the last remaining key descriptions and review some more, where I feel it's a bit roughly documented. Anyone who want to do a review, please feel free.