[ENH] Add tag to cli for "only" content

jupyter_book/cli/main.py

@@ -124,6 +124,12 @@ def main():
     "This can only be used with --builder=custom. Valid options listed at "
     "https://www.sphinx-doc.org/en/master/man/sphinx-build.html",
 )
+@click.option(
+    "--tag",
+    multiple=True,
+    default=None,
+    help="Identify tag for including conditional content using the only directive.",
+)
 @click.option(
     "-v", "--verbose", count=True, help="increase verbosity (can be repeated)"
 )
@@ -150,6 +156,7 @@ def build(
     freshenv,
     builder,
     custom_builder,
+    tag,
     verbose,
     quiet,
     individualpages,
@@ -302,6 +309,9 @@ def build(
         click.style("Output Path: ", bold=True, fg="blue")
         + click.format_filename(f"{OUTPUT_PATH}")
     )
+    click.echo(
+        click.style("Including tag: ", bold=True, fg="blue") + click.style(f"{tag}")
+    )
 
     # Now call the Sphinx commands to build
     result = build_sphinx(
@@ -312,6 +322,7 @@ def build(
         path_config=path_config,
         confoverrides=config_overrides,
         builder=BUILDER_OPTS[builder],
+        tags=tag,
         warningiserror=warningiserror,
         keep_going=keep_going,
         freshenv=freshenv,

tests/pages/single_page.ipynb

@@ -44,6 +44,33 @@
     "````"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Conditional content\n",
+    "## Single tag\n",
+    "\n",
+    "The only directive can use a single tag:\n",
+    "\n",
+    "```{only} cowboy\n",
+    "This note is not for city slickers!\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Boolean tag\n",
+    "\n",
+    "And you can use multiple tags:\n",
+    "\n",
+    "```{only} cowboy and cowgirl\n",
+    "This note is for cowboys and cowgirls!\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

tests/test_build.py

@@ -309,3 +309,56 @@ def test_toc_numbered(
         basename=toc_file.split(".")[0],
         extension=f"{SPHINX_VERSION}.html",
     )
+
+
+def test_only(pages, cli):
+    """Test {only} content is not built."""
+    page = pages.joinpath("single_page.ipynb")
+    html = pages.joinpath("_build", "_page", "single_page", "html")
+    result = cli.invoke(commands.build, [page.as_posix(), "-n", "-W", "--keep-going"])
+    assert result.exit_code == 0, result.output
+    assert html.joinpath("single_page.html").exists()
+    outpage = html.joinpath("single_page.html")
+    assert not html.joinpath("extra_page.html").exists()
+    assert "slickers" not in outpage.read_text(encoding="utf8")
+    assert "cowgirls" not in outpage.read_text(encoding="utf8")
+
+
+def test_only_tag(pages, cli):
+    """Test tag cli builds {only} content."""
+    page = pages.joinpath("single_page.ipynb")
+    html = pages.joinpath("_build", "_page", "single_page", "html")
+    result = cli.invoke(
+        commands.build, [page.as_posix(), "-n", "-W", "--keep-going", "--tag", "cowboy"]
+    )
+    assert result.exit_code == 0, result.output
+    assert html.joinpath("single_page.html").exists()
+    outpage = html.joinpath("single_page.html")
+    assert not html.joinpath("extra_page.html").exists()
+    assert "slickers" in outpage.read_text(encoding="utf8")
+    assert "cowgirls" not in outpage.read_text(encoding="utf8")
+
+
+def test_both_tags(pages, cli):
+    """Test multiple tag creates boolean condition."""
+    page = pages.joinpath("single_page.ipynb")
+    html = pages.joinpath("_build", "_page", "single_page", "html")
+    result = cli.invoke(
+        commands.build,
+        [
+            page.as_posix(),
+            "-n",
+            "-W",
+            "--keep-going",
+            "--tag",
+            "cowboy",
+            "--tag",
+            "cowgirl",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert html.joinpath("single_page.html").exists()
+    outpage = html.joinpath("single_page.html")
+    assert not html.joinpath("extra_page.html").exists()
+    assert "slickers" in outpage.read_text(encoding="utf8")
+    assert "cowgirls" in outpage.read_text(encoding="utf8")