Create the typer-click object when run from sphinx (#17)

This is necessary so we can auto-generate CLI documentation using sphinx-click plugin.
That's the easiest way currently do document typer CLI fastapi/typer#200 (comment)

Author: rth

CHANGELOG.md

@@ -4,15 +4,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2022-12-18
+### Added
+ - Define `pyodide_cli.app.typer_click_object` when `pyodide_cli` is imported from within sphinx,
+   to allow auto-generate CLI documentation with [sphinx-click](https://sphinx-click.readthedocs.io/en/latest/)
+   ([#17](https://github.com/pyodide/pyodide-cli/pull/17))
+
+
 ## [0.2.0] - 2022-09-04
 ### Added
  - When registering commands, you can pass extra arguments to the typer's `app.command` method, by setting
    CLI entry point function attribute `typer_kwargs` to the corresponding kwargs dict.
-   ([#4](https://github.com/pyodide/pyodide-cli/pull/2))
+   ([#2](https://github.com/pyodide/pyodide-cli/pull/2))
 
 ### Changed
 
- - Fix entry point registration for callable functions ([#4](https://github.com/pyodide/pyodide-cli/pull/2))
+ - Fix entry point registration for callable functions ([#4](https://github.com/pyodide/pyodide-cli/pull/4))
 
 ## [0.1.0] - 2022-09-02
 

pyodide_cli/app.py

@@ -1,3 +1,4 @@
+import sys
 from importlib.metadata import entry_points
 
 import typer  # type: ignore[import]
@@ -29,6 +30,7 @@ def callback(
 
 
 def register_plugins():
+    """Register subcommands via the ``pyodide.cli`` entry-point"""
     eps = entry_points(group="pyodide.cli")
     plugins = {ep.name: ep.load() for ep in eps}
     for plugin_name, module in plugins.items():
@@ -46,5 +48,10 @@ def main():
     app()
 
 
+if "sphinx" in sys.modules and __name__ != "__main__":
+    # Create the typer click object to generate docs with sphinx-click
+    register_plugins()
+    typer_click_object = typer.main.get_command(app)
+
 if __name__ == "__main__":
     main()

pyodide_cli/tests/test_cli.py

@@ -1,7 +1,35 @@
+from multiprocessing import Process, Queue
 from subprocess import check_output
 
 
 def test_cli_help():
     output = check_output(["pyodide", "--help"]).decode("utf-8")
     msg = "A command line interface for Pyodide."
     assert msg in output
+
+
+def test_click_click_object_defintion():
+    # By default the typer-click-object is not defined
+    # Run in a separate process to make s
+    q = Queue()
+
+    def func(q: Queue, with_sphinx=False):
+        import sys
+
+        if with_sphinx:
+            sys.modules["sphinx"] = None  # type: ignore
+        import pyodide_cli.app
+
+        q.put(dir(pyodide_cli.app))
+
+    p = Process(target=func, args=(q,))
+    p.start()
+    p.join()
+    app_dir = q.get()
+    assert "typer_click_object" not in app_dir
+
+    p = Process(target=func, args=(q,), kwargs={"with_sphinx": True})
+    p.start()
+    p.join()
+    app_dir = q.get()
+    assert "typer_click_object" in app_dir