Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs command reference #82

Merged
merged 2 commits into from
Jan 14, 2025
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Docs: add command reference
grst committed Jan 14, 2025
commit 75abd9ab7620f5332f49509632c83e0e803b090d
44 changes: 22 additions & 22 deletions docs/command_reference.md
Original file line number Diff line number Diff line change
@@ -12,86 +12,86 @@

```{eval-rst}
.. click:run::
from dso.cli import cli as dso
from dso.cli import dso
invoke(dso, args=["compile-config", "--help"])
```

## dso create

```{eval-rst}
.. click:run::
from dso.cli._create import create_cli
invoke(create_cli, args=["--help"])
from dso.cli import dso
invoke(dso, args=["create", "--help"])
```

### dso create folder

```{eval-rst}
.. click:run::
from dso.cli._create import create_folder_cli
invoke(create_folder_cli, args=["--help"])
from dso.cli import dso
invoke(dso, args=["create", "folder", "--help"])
```

### dso create stage

```{eval-rst}
.. click:run::
from dso.cli._create import create_stage_cli
invoke(create_stage_cli, args=["--help"])
from dso.cli import dso
invoke(dso, args=["create", "stage", "--help"])
```

## dso exec

```{eval-rst}
.. click:run::
from dso.cli import exec_cli
invoke(exec_cli, args=["--help"])
from dso.cli import dso
invoke(dso, args=["exec", "--help"])
```

### dso exec quarto

```{eval-rst}
.. click:run::
from dso.cli._exec import exec_quarto_cli
invoke(exec_quarto_cli, args=["--help"])
from dso.cli import dso
invoke(dso, args=["exec", "quarto" ,"--help"])
```

## dso get-config

```{eval-rst}
.. click:run::
from dso.cli import get_config_cli
invoke(get_config_cli, args=["--help"])
from dso.cli import dso
invoke(dso, args=["get-config", "--help"])
```

## dso init

```{eval-rst}
.. click:run::
from dso.cli import init_cli
invoke(init_cli, args=["--help"])
from dso.cli import dso
invoke(dso, args=["init", "--help"])
```

## dso lint

```{eval-rst}
.. click:run::
from dso.cli import lint_cli
invoke(lint_cli, args=["--help"])
from dso.cli import dso
invoke(dso, args=["lint", "--help"])
```

## dso repro

```{eval-rst}
.. click:run::
from dso.cli import repro_cli
invoke(repro_cli, args=["--help"])
from dso.cli import dso
invoke(dso, args=["repro", "--help"])
```

## watermark cli
## dso watermark

```{eval-rst}
.. click:run::
from dso.cli import watermark_cli
invoke(watermark_cli, args=["--help"])
from dso.cli import dso
invoke(dso, args=["watermark", "--help"])
```
9 changes: 8 additions & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
@@ -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")],
]

1 change: 1 addition & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -15,6 +15,7 @@ getting_started.md
:maxdepth: 1
:caption: DSO CLI

command_reference.md
CHANGELOG.md
contributing.md
```
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"
34 changes: 17 additions & 17 deletions src/dso/cli/__init__.py
Original file line number Diff line number Diff line change
@@ -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)
10 changes: 5 additions & 5 deletions src/dso/cli/_create.py
Original file line number Diff line number Diff line change
@@ -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)
6 changes: 3 additions & 3 deletions src/dso/cli/_exec.py
Original file line number Diff line number Diff line change
@@ -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)
6 changes: 3 additions & 3 deletions tests/conftest.py
Original file line number Diff line number Diff line change
@@ -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(
4 changes: 2 additions & 2 deletions tests/test_cli.py
Original file line number Diff line number Diff line change
@@ -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
8 changes: 4 additions & 4 deletions tests/test_compile_config.py
Original file line number Diff line number Diff line change
@@ -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
Loading