Add `:cminx: no-doc` directive

[JackNoordhuis]

Is this pull request associated with an issue(s)? There are no issues associated with these changes. The changes are proposed as a feature addition for consideration by maintainers.

Description Intended to be used with configuration options: include_undocumented_function: true include_undocumented_macro: true CMake files may contain internal methods/macros that should not appear in end-user documentation, but not all end-user methods/macros contain explicit documentation (yet? – aim to ease adoption.)

The use case that inspired these changes comes from an internal CMake module where steps of a large function are broken into smaller macros. The chosen approach allows all documentation comments to remain consistent by respecting a declaration that tells CMinx it should not generate documentation for a certain construct. An alternate approach would be similar to existing configuration options. A regex could be supplied to match a prefix, conveying meaning to CMinx that documentation should not be generated for matching constructs. In contrast to jumping through external files and mentally parsing regex expressions – an explicit directive conveys meaning directly in the source code for maintainers working on the affected code.

Summary of changes

• Add :cminx: no-doc directive for skipping RST generation
  • Renames documentation_types.DocumentationType.process() to documentation_types.DocumentationType.process_rst() (now considered a step of processing)
  • Reintroduces documentation_types.DocumentationType.process() as non-abstract entry point for processing
  • In short: regex_replace('src/cminx/documentation_types.py', '(?<! {4}\@abstractmethod\n)( {4}def) process(\(self, writer: (?:RSTWriter|Directive)\))', '$1 process_rst$2')
• test/test_samples: add :cminx: no-doc directive test

[CLAassistant]

All committers have signed the CLA.

[ryanmrichard]

@JackNoordhuis Thanks for the contribution. Unfortunately, I'm pretty busy at the moment so I probably won't have a chance to look at this until maybe Friday or early next week.

@AutonomicPerfectionist I know you've moved on to other things, but if you have a couple cycles I would love some help reviewing this. If you don't have the time, no worries.

[AutonomicPerfectionist]

@ryanmrichard yep I can take a quick look in a bit

[ryanmrichard]

Converted this PR to issue #160