docs command reference (#82)

* Sphinx command reference with click_extra

* Docs: add command reference

docs/command_reference.md

@@ -0,0 +1,97 @@
+# Command reference
+
+## dso
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["--help"])
+```
+
+## dso compile-config
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["compile-config", "--help"])
+```
+
+## dso create
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["create", "--help"])
+```
+
+### dso create folder
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["create", "folder", "--help"])
+```
+
+### dso create stage
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["create", "stage", "--help"])
+```
+
+## dso exec
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["exec", "--help"])
+```
+
+### dso exec quarto
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["exec", "quarto" ,"--help"])
+```
+
+## dso get-config
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["get-config", "--help"])
+```
+
+## dso init
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["init", "--help"])
+```
+
+## dso lint
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["lint", "--help"])
+```
+
+## dso repro
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["repro", "--help"])
+```
+
+## dso watermark
+
+```{eval-rst}
+.. click:run::
+    from dso.cli import dso
+    invoke(dso, args=["watermark", "--help"])
+```

docs/conf.py

@@ -9,6 +9,13 @@
 from datetime import datetime
 from importlib.metadata import metadata
 from pathlib import Path
+import os
+import rich_click as click
+
+# set maximum width for help pages
+click.rich_click.MAX_WIDTH = 96
+# Set force color for rich outputs shown in the docs
+os.environ["FORCE_COLOR"] = "1"
 
 HERE = Path(__file__).parent
 sys.path.insert(0, str(HERE / "extensions"))
@@ -58,7 +65,7 @@
     "sphinx.ext.mathjax",
     "IPython.sphinxext.ipython_console_highlighting",
     "sphinxext.opengraph",
-    "sphinxcontrib.programoutput",
+    "click_extra.sphinx",
     *[p.stem for p in (HERE / "extensions").glob("*.py")],
 ]
 

docs/index.md

@@ -15,6 +15,7 @@ getting_started.md
 :maxdepth: 1
 :caption: DSO CLI
 
+command_reference.md
 CHANGELOG.md
 contributing.md
 ```

pyproject.toml

@@ -41,6 +41,7 @@ dependencies = [
 
 optional-dependencies.dev = [ "hatch", "pre-commit" ]
 optional-dependencies.doc = [
+  "click-extra[sphinx]",
   "docutils>=0.8,!=0.18.*,!=0.19.*",
   # For notebooks
   "ipykernel",
@@ -52,7 +53,6 @@ optional-dependencies.doc = [
   "sphinx-book-theme>=1",
   "sphinx-copybutton",
   "sphinxcontrib-bibtex>=1",
-  "sphinxcontrib-programoutput>=0.18",
   "sphinxext-opengraph",
 ]
 optional-dependencies.test = [
@@ -67,7 +67,7 @@ optional-dependencies.test = [
 urls.Documentation = "https://github.com/Boehringer-Ingelheim/dso"
 urls.Home-page = "https://github.com/Boehringer-Ingelheim/dso"
 urls.Source = "https://github.com/Boehringer-Ingelheim/dso"
-scripts.dso = "dso.cli:cli"
+scripts.dso = "dso.cli:dso"
 
 [tool.hatch.version]
 source = "vcs"

src/dso/cli/__init__.py

@@ -15,15 +15,15 @@
 from dso._metadata import __version__
 from dso._util import get_project_root, get_template_path, instantiate_with_repo
 
-from ._create import create_cli
-from ._exec import exec_cli
+from ._create import dso_create
+from ._exec import dso_exec
 
 click.rich_click.USE_MARKDOWN = True
 
 
 @click.command(name="compile-config")
 @click.argument("args", nargs=-1)
-def compile_config_cli(args):
+def dso_compile_config(args):
     """Compile params.in.yaml into params.yaml using Jinja2 templating and resolving recursive templates.
 
     If passing no arguments, configs will be resolved for the current working directory (i.e. all parent configs,
@@ -58,7 +58,7 @@ def compile_config_cli(args):
 @click.argument(
     "stage",
 )
-def get_config_cli(stage, all, skip_compile):
+def dso_get_config(stage, all, skip_compile):
     """Get the configuration for a given stage and print it to STDOUT in yaml format.
 
     The path to the stage must be relative to the root dir of the project.
@@ -85,7 +85,7 @@ def get_config_cli(stage, all, skip_compile):
 @click.command(
     "init",
 )
-def init_cli(name: str | None = None, description: str | None = None):
+def dso_init(name: str | None = None, description: str | None = None):
     """
     Initialize a new project. A project can contain several stages organized in arbitrary subdirectories.
 
@@ -122,7 +122,7 @@ def init_cli(name: str | None = None, description: str | None = None):
     is_flag=True,
 )
 @click.argument("args", nargs=-1)
-def lint_cli(args, skip_compile: bool = False):
+def dso_lint(args, skip_compile: bool = False):
     """Lint a dso project
 
     Performs consistency checks according to a set of rules.
@@ -149,7 +149,7 @@ def lint_cli(args, skip_compile: bool = False):
     context_settings={"ignore_unknown_options": True},
 )
 @click.argument("args", nargs=-1, type=click.UNPROCESSED)
-def repro_cli(args):
+def dso_repro(args):
     """Wrapper around dvc repro, compiling configuration before running."""
     from dso._compile_config import compile_all_configs
     from dso._util import check_ask_pre_commit
@@ -176,7 +176,7 @@ def repro_cli(args):
 @click.option("--font_outline", type=int)
 @click.option("--font_color", help="Use RGBA (e.g. `#AAAAAA88`) to specify transparency")
 @click.option("--font_outline_color", help="Use RGBA (e.g. `#AAAAAA88`) to specify transparency")
-def watermark_cli(input_image, output_image, text, **kwargs):
+def dso_watermark(input_image, output_image, text, **kwargs):
     """Add a watermark to an image
 
     To be called from the dso-r package for implementing a custom graphics device.
@@ -211,7 +211,7 @@ def watermark_cli(input_image, output_image, text, **kwargs):
     is_flag=True,
 )
 @click.version_option(version=__version__, prog_name="dso")
-def cli(quiet: int, verbose: bool):
+def dso(quiet: int, verbose: bool):
     """Root command"""
     if quiet >= 2:
         log.setLevel(logging.ERROR)
@@ -224,11 +224,11 @@ def cli(quiet: int, verbose: bool):
         os.environ["DSO_VERBOSE"] = "1"
 
 
-cli.add_command(create_cli)
-cli.add_command(init_cli)
-cli.add_command(compile_config_cli)
-cli.add_command(repro_cli)
-cli.add_command(exec_cli)
-cli.add_command(lint_cli)
-cli.add_command(get_config_cli)
-cli.add_command(watermark_cli)
+dso.add_command(dso_create)
+dso.add_command(dso_init)
+dso.add_command(dso_compile_config)
+dso.add_command(dso_repro)
+dso.add_command(dso_exec)
+dso.add_command(dso_lint)
+dso.add_command(dso_get_config)
+dso.add_command(dso_watermark)

src/dso/cli/_create.py

@@ -33,7 +33,7 @@
 @click.option("--template", type=click.Choice(list(STAGE_TEMPLATES)))
 @click.argument("name", required=False)
 @click.command("stage", help=CREATE_STAGE_HELP_TEXT)
-def create_stage_cli(name: str | None = None, template: str | None = None, description: str | None = None):
+def dso_create_stage(name: str | None = None, template: str | None = None, description: str | None = None):
     """Create a new stage."""
     import questionary
 
@@ -71,7 +71,7 @@ def create_stage_cli(name: str | None = None, template: str | None = None, descr
 
 @click.argument("name", required=False)
 @click.command("folder")
-def create_folder_cli(name: str | None = None):
+def dso_create_folder(name: str | None = None):
     """Create a new folder. A folder can contain subfolders or stages.
 
     Technically, nothing prevents you from just using `mkdir`. This command additionally adds some default
@@ -102,10 +102,10 @@ def create_folder_cli(name: str | None = None):
 
 
 @click.group(name="create")
-def create_cli():
+def dso_create():
     """Create stage folder structure subcommand."""
     pass
 
 
-create_cli.add_command(create_stage_cli)
-create_cli.add_command(create_folder_cli)
+dso_create.add_command(dso_create_stage)
+dso_create.add_command(dso_create_folder)

src/dso/cli/_exec.py

@@ -16,7 +16,7 @@
     default=bool(int(os.environ.get("DSO_SKIP_COMPILE", 0))),
     is_flag=True,
 )
-def exec_quarto_cli(stage: str, skip_compile: bool = True):
+def dso_exec_quarto(stage: str, skip_compile: bool = True):
     """
     Render a quarto stage. Quarto parameters are inherited from params.yaml
 
@@ -84,9 +84,9 @@ def exec_quarto_cli(stage: str, skip_compile: bool = True):
 
 
 @click.group(name="exec")
-def exec_cli():
+def dso_exec():
     """Dso wrappers around various tools"""
     pass
 
 
-exec_cli.add_command(exec_quarto_cli)
+dso_exec.add_command(dso_exec_quarto)

tests/conftest.py

@@ -6,7 +6,7 @@
 from pytest import fixture
 
 from dso._compile_config import compile_all_configs
-from dso.cli import create_cli, init_cli
+from dso.cli import dso_create, dso_init
 
 TESTDATA = Path(__file__).parent / "data"
 
@@ -17,7 +17,7 @@ def dso_project(tmp_path) -> Path:
     runner = CliRunner()
     proj_name = "dso_project"
     chdir(tmp_path)
-    runner.invoke(init_cli, [proj_name, "--description", "a test project"])
+    runner.invoke(dso_init, [proj_name, "--description", "a test project"])
 
     return tmp_path / proj_name
 
@@ -31,7 +31,7 @@ def quarto_stage(dso_project) -> Path:
     runner = CliRunner()
     stage_name = "quarto_stage"
     chdir(dso_project)
-    runner.invoke(create_cli, ["stage", stage_name, "--template", "quarto", "--description", "a quarto stage"])
+    runner.invoke(dso_create, ["stage", stage_name, "--template", "quarto", "--description", "a quarto stage"])
     with (Path(stage_name) / "src" / f"{stage_name}.qmd").open("w") as f:
         f.write(
             dedent(

tests/test_cli.py

@@ -1,9 +1,9 @@
 from click.testing import CliRunner
 
-from dso.cli import cli
+from dso.cli import dso
 
 
 def test_root_command():
     runner = CliRunner()
-    result = runner.invoke(cli)
+    result = runner.invoke(dso)
     assert result.exit_code == 0

tests/test_compile_config.py

@@ -14,7 +14,7 @@
     _get_parent_configs,
     _load_yaml_with_auto_adjusting_paths,
 )
-from dso.cli import compile_config_cli
+from dso.cli import dso_compile_config
 
 
 def _setup_yaml_configs(tmp_path, configs: dict[str, dict]):
@@ -94,7 +94,7 @@ def test_auto_adjusting_path_with_jinja(tmp_path, test_yaml, expected):
         with test_file.open("w") as f:
             f.write(dedent(test_yaml))
 
-        result = runner.invoke(compile_config_cli, [])
+        result = runner.invoke(dso_compile_config, [])
         print(result.output)
         td = Path(td)
         assert result.exit_code == 0
@@ -115,7 +115,7 @@ def test_compile_configs(tmp_path):
                 "A/B/C/params.in.yaml": {"value": "C", "jinja2": "{{ only_root }}", "list": [5]},
             },
         )
-        result = runner.invoke(compile_config_cli, [])
+        result = runner.invoke(dso_compile_config, [])
         print(result.output)
         td = Path(td)
         assert result.exit_code == 0
@@ -140,7 +140,7 @@ def test_compile_configs_null_override(tmp_path):
                 "A/B/params.in.yaml": {"str": None, "list": None, "dict": None, "null": None},
             },
         )
-        result = runner.invoke(compile_config_cli, [])
+        result = runner.invoke(dso_compile_config, [])
         print(result.output)
         td = Path(td)
         assert result.exit_code == 0