IMPROVE: adding dirhtml builder (#1092)

docs/advanced/pdf.md

@@ -9,7 +9,7 @@ PDF building is experimental, and may change or have bugs.
 
 There are two approaches to building PDF files.
 
-(pdf-html)=
+(pdf:html)=
 ## Build a PDF from your book HTML
 
 It is possible to build a single PDF from your book's HTML. This starts by
@@ -78,7 +78,7 @@ For example, to **hide the right table of contents** at print time, you could ad
 
 The right Table of Contents would be present in your live website, but hidden when someone printed a PDF of your website.
 
-(pdf/latex)=
+(pdf:latex)=
 ## Build a PDF using LaTeX
 
 You can also use LaTeX to build a PDF of your book.

docs/contribute/intro.md

@@ -73,11 +73,11 @@ If you'd like to test (or try out) the generation of PDFs, take the following st
 **To generate PDFs via HTML**, make sure you install Jupyter Book with
 `pip install -e .[pdfhtml]`. This will install [`pyppeteer`](https://github.com/pyppeteer/pyppeteer),
 which runs a headless chrome session to convert your book to PDF. Next, follow
-the installation instructions at {ref}`pdf-html`. You should then be able to build your
+the installation instructions at {ref}`pdf:html`. You should then be able to build your
 book's PDF through HTML.
 
 **To generate PDFs via LaTeX**, make sure you install a working LaTeX distribution locally.
-Do so by following the instructions in {ref}`pdf/latex`.
+Do so by following the instructions in {ref}`pdf:latex`.
 
 If you have installed the requirements for both HTML and LaTeX generation, you should
 be able to run the full test suite with pytest.

docs/customize/toc.md

@@ -211,7 +211,7 @@ tips and best-practices.
 
 ```{note}
 This is particularly important when you [number your book's sections](toc/numbering)
-or when you [build a PDF of your book through Latex](pdf/latex).
+or when you [build a PDF of your book through Latex](pdf:latex).
 ```
 
 **Chapters are at the top of your book hierarchy**. The top level of your `_toc.yml` contains

docs/start/build.md

@@ -95,6 +95,18 @@ Either double-click the html file in your local folder, or enter the absolute
 path to the file in your browser navigation bar adding `file://` at the beginning
 (e.g. `file://Users/my_path_to_book/_build/index.html`).
 
+## Other builder types
+
+You can build a variety of outputs using Jupyter Book. To choose a different builder, use the `--builder <builder-name>` configuration when running `jupyter-book build` from the command-line. Here is a list of builders that are available to you:
+
+- `html`: HTML outputs (default)
+- `singlehtml`: A single HTML page for your book
+- `dirhtml`: HTML outputs with `<filename>/index.html` structure.
+- `pdfhtml`: Build a PDF via HTML outputs (see [](pdf:html))
+- `linkcheck`: Run the Sphinx link checker
+- `latex`: Build Latex files for your book
+- `pdflatex`: Build a PDF of your book via Latex (see [](pdf:latex))
+
 ## Next step: publish your book
 
 Now that you've created the HTML for your book, it's time to publish it online.

jupyter_book/commands/__init__.py

@@ -58,6 +58,7 @@ def main():
 
 BUILDER_OPTS = {
     "html": "html",
+    "dirhtml": "dirhtml",
     "pdfhtml": "singlehtml",
     "latex": "latex",
     "pdflatex": "latex",
@@ -246,6 +247,8 @@ def build(
         OUTPUT_PATH = BUILD_PATH.joinpath("html")
     elif builder in ["latex", "pdflatex"]:
         OUTPUT_PATH = BUILD_PATH.joinpath("latex")
+    elif builder in ["dirhtml"]:
+        OUTPUT_PATH = BUILD_PATH.joinpath("dirhtml")
 
     if nitpick:
         config_overrides["nitpicky"] = True

tests/test_build.py

@@ -49,6 +49,20 @@ def test_build_from_template(temp_with_override, cli):
     assert html.joinpath("intro.html").exists()
 
 
+def test_build_dirhtml_from_template(temp_with_override, cli):
+    """Test building the book template with dirhtml."""
+    # Create the book from the template
+    book = temp_with_override / "new_book"
+    _ = cli.invoke(commands.create, book.as_posix())
+    build_result = cli.invoke(
+        commands.build, [book.as_posix(), "-n", "-W", "--builder", "dirhtml"]
+    )
+    assert build_result.exit_code == 0, build_result.output
+    html = book.joinpath("_build", "dirhtml")
+    assert html.joinpath("index.html").exists()
+    assert html.joinpath("intro", "index.html").exists()
+
+
 def test_custom_config(cli, build_resources):
     """Test a variety of custom configuration values."""
     books, _ = build_resources