Allow macros to be hidden from documentation

[Ryan J Ollos]

For "internal use only" macros like WikiMacros#LatestRelease-macro, it would be good to hide from the wiki macro help. We could either hide the macros with no documentation, or have a class attribute that indicates the macro should be hidden.

Another possible application is to hide documentation for that require a permission that the user does not possess.

[Ryan J Ollos]

The proposed changes (log:rjollos.git:t13056_hidden_macros)

• Are backward-compatible
• Allow hiding a macro help using _description = None

If that change looks okay I'll add tests.

To hide macro documentation based on user permissions we'd need to pass formatter to get_macro_description, so that formatter.req could be used. To be consistent with arguments of other methods we'd have to change:

- def get_macro_description(self, name):
+ def get_macro_description(self, formatter, name):

I don't have a particular use for that change now, so I'll skip it.

[Jun Omae]

I like to add property to hide (e.g. hidden_macro_index) like IRequestHandler.is_valid_default_handler rather than _description = None.

If you'd like to use macro description is None, I think we should add the same document to IWikiMacroProvider.get_macro_description(). Macro can be implemented IWikiMacroProvider without WikiMacroBase.

Also, ​th:WikiAutoCompletePlugin uses WikiSystem.macro_providers and get_macro_description(). It might be good to provide patch.

[Ryan J Ollos]

Replying to Jun Omae:

I like to add property to hide (e.g. hidden_macro_index) like IRequestHandler.is_valid_default_handler rather than _description = None.

Sounds good. I will make those changes.

[Ryan J Ollos]

Proposed changes with test coverage: [e20f620b1/rjollos.git].

[Ryan J Ollos]

Committed in r17053, r17054.