docs: fix missing api reference for Emitter

The docs were missing because of the ``__all__`` attribute in
``messages.py``. To get around this, craft a special purpose rst file to
be used when documenting that module, explicitly asking autodoc to
generate docs for Emitter and EmitterMode.

Fixes #208

craft_cli/messages.py

@@ -24,6 +24,7 @@
 ]
 
 import enum
+import functools
 import logging
 import os
 import pathlib
@@ -406,6 +407,7 @@ def _active_guard(ignore_when_stopped: bool = False) -> Callable[..., Any]:  # n
     """
 
     def decorator(wrapped_func: FuncT) -> FuncT:
+        @functools.wraps(wrapped_func)
         def func(self: Emitter, *args: Any, **kwargs: Any) -> Any:
             if not self._initiated:
                 raise RuntimeError("Emitter needs to be initiated first")
@@ -433,14 +435,14 @@ class Emitter:
     to show:
 
     - `message`: for the final output of the running command; if there is important information
-    that needs to be shown to the user in the middle of the execution (and not overwritten
-    by other messages) this method can be also used but passing intermediate=True.
+      that needs to be shown to the user in the middle of the execution (and not overwritten
+      by other messages) this method can be also used but passing intermediate=True.
 
     - `progress`: for all the progress messages intended to provide information that the
-    machinery is running and doing what.
+      machinery is running and doing what.
 
     - `trace`: for all the messages that may used by the *developers* to do any debugging on
-    the application behaviour and/or logs forensics.
+      the application behaviour and/or logs forensics.
     """
 
     def __init__(self) -> None:

docs/autodoc/craft_cli.messages.template

@@ -0,0 +1,14 @@
+..
+  Note: This file replaces the one generated by apidoc at build-time because
+  we want to use different settings - specifically, we want to spell out the
+  members that we want to document (EmitterMode and Emitter), ignoring the
+  ``message`` module's ``__all__``.
+
+
+craft\_cli.messages module
+==========================
+
+.. automodule:: craft_cli.messages
+   :members: Emitter, EmitterMode
+   :undoc-members:
+   :show-inheritance:

docs/custom_conf.py

@@ -187,8 +187,10 @@
 
 # region Setup reference generation
 def run_apidoc(_):
+    from pathlib import Path
     from sphinx.ext.apidoc import main
     import os
+    import shutil
     import sys
 
     sys.path.append(os.path.join(os.path.dirname(__file__), ".."))
@@ -197,6 +199,12 @@ def run_apidoc(_):
     exclude_patterns = ["*pytest_plugin*"]
     main(["-e", "--no-toc", "--force", "-o", cur_dir, module, *exclude_patterns])
 
+    # After calling apidoc, replace the one generated for the ``messages``
+    # module with our special one that spells out the items to document.
+    messages = Path(cur_dir) / "autodoc/craft_cli.messages.template"
+    assert messages.is_file()
+    shutil.copy(messages, Path(cur_dir) / "craft_cli.messages.rst")
+
 
 def no_namedtuple_attrib_docstring(app, what, name, obj, options, lines):
     """Strips out silly "Alias for field number" lines in namedtuples reference."""