fix: quickstart

ApeWorX · Oct 3, 2024 · 607fe97 · 607fe97
1 parent 3523d58
commit 607fe97
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# Quick Start
+# Overview
 
 `sphinx-ape` is a documentation plugin for the Sphinx framework.
 The purpose of this plugin to share code for generating documentation across all ApeWorX repositories.

diff --git a/sphinx_ape/_base.py b/sphinx_ape/_base.py
@@ -1,3 +1,4 @@
+from functools import cached_property
 from pathlib import Path
 from typing import Optional
 
@@ -6,12 +7,12 @@
 
 class Documentation:
     def __init__(self, base_path: Optional[Path] = None, name: Optional[str] = None) -> None:
-        self._base_path = base_path or Path.cwd()
+        self.base_path = base_path or Path.cwd()
         self._name = name or get_package_name()
 
     @property
     def docs_path(self) -> Path:
-        return self._base_path / "docs"
+        return self.base_path / "docs"
 
     @property
     def root_build_path(self) -> Path:
@@ -49,11 +50,13 @@ def conf_file(self) -> Path:
     def index_file(self) -> Path:
         return self.build_path / "index.html"
 
-    def init(self):
+    def init(self, include_quickstart: bool = True):
         if not self.docs_path.is_dir():
             self.docs_path.mkdir()
 
-        self._ensure_quickstart_exists()
+        if include_quickstart:
+            self._ensure_quickstart_exists()
+
         self._ensure_conf_exists()
         self._ensure_index_exists()
 
@@ -81,15 +84,25 @@ def _ensure_quickstart_exists(self):
         self.userguides_path.mkdir(exist_ok=True)
         quickstart_path.write_text("```{include} ../../README.md\n```\n")
 
+    @cached_property
+    def quickstart_name(self) -> Optional[str]:
+        guides = self._get_filenames(self.userguides_path)
+        for guide in guides:
+            if guide == "quickstart":
+                return guide
+            elif guide == "overview":
+                return guide
+
+        return None
+
     @property
     def userguide_names(self) -> list[str]:
         guides = self._get_filenames(self.userguides_path)
-        quickstart_name = "userguides/quickstart"
-        if quickstart_name in guides:
-            # Make sure quick start is first.
-            guides = [quickstart_name, *[g for g in guides if g != quickstart_name]]
+        if not (quickstart := self.quickstart_name):
+            # Guides has no quickstart.
+            return guides
 
-        return guides
+        return [quickstart, *[g for g in guides if g != quickstart]]
 
     @property
     def cli_reference_names(self) -> list[str]:

diff --git a/sphinx_ape/_cli.py b/sphinx_ape/_cli.py
@@ -102,7 +102,7 @@ def serve(base_path, host, port, open):
             ]
             if len(built_docs) == 1:
                 # Only one package, dir-listing not necessary.
-                url = f"{url}{built_docs[0]}/latest"
+                url = f"{url}{built_docs[0]}"
 
             click.launch(url)
 

diff --git a/sphinx_ape/build.py b/sphinx_ape/build.py
@@ -12,7 +12,7 @@
 <!DOCTYPE html>
 <meta charset="utf-8">
 <title>Redirecting...</title>
-<meta http-equiv="refresh" content="0; URL=./{}/">
+<meta http-equiv="refresh" content="0; URL=./{}">
 """
 
 
@@ -132,7 +132,7 @@ def _publish(self, repository: Optional[str] = None, push: bool = True):
         else:
             repo_url = extract_source_url()
 
-        gh_pages_path = self._base_path / "gh-pages"
+        gh_pages_path = self.base_path / "gh-pages"
         git(
             "clone",
             repo_url,
@@ -207,7 +207,12 @@ def _build_release(self):
 
     def _setup_redirect(self):
         self.build_path.mkdir(exist_ok=True, parents=True)
-        redirect = "stable" if self.stable_path.is_dir() else "latest"
+        redirect = "stable/" if self.stable_path.is_dir() else "latest/"
+
+        # When there is a quickstart, redirect to that instead of the toctree root.
+        if quickstart := self.quickstart_name:
+            redirect = f"{redirect}userguides/{quickstart}.html"
+
         # We replace it to handle the case when stable has joined the chat.
         self.index_file.unlink(missing_ok=True)
         self.index_file.write_text(REDIRECT_HTML.format(redirect))

diff --git a/tests/test_build.py b/tests/test_build.py
@@ -45,6 +45,29 @@ def run_mock_sphinx(path, *args, **kwargs):
     def mock_git(self, mocker):
         return mocker.patch("sphinx_ape.build.git")
 
+    @pytest.mark.parametrize(
+        "quickstart_name,quickstart_title",
+        [
+            ("quickstart", "Overview"),
+            ("overview", "Overview"),
+            ("quickstart", "Quickstart"),
+            ("overview", "Quickstart"),
+        ],
+    )
+    def test_userguide_names(self, temp_path, quickstart_name, quickstart_title):
+        builder = DocumentationBuilder(mode=BuildMode.LATEST, base_path=temp_path)
+        builder.init(include_quickstart=False)
+        builder.userguides_path.mkdir(parents=True, exist_ok=True)
+        guide1 = builder.userguides_path / "guide1.md"
+        guide1.write_text("# Guide\n\nThis is a guide\n")
+        overview = builder.userguides_path / f"{quickstart_name}.md"
+        overview.write_text(f"# {quickstart_title}\n\nThis is a quickstart")
+
+        actual = builder.userguide_names
+        # NOTE: Quickstart always comes first!
+        expected = [quickstart_name, "guide1"]
+        assert actual == expected
+
     def test_build_latest(self, temp_path):
         builder = DocumentationBuilder(mode=BuildMode.LATEST, base_path=temp_path)
         builder.init()  # so there is something to build.
@@ -53,7 +76,7 @@ def test_build_latest(self, temp_path):
 
         # Ensure re-direct exists and points to latest/.
         assert builder.index_file.is_file()
-        expected_content = REDIRECT_HTML.format("latest")
+        expected_content = REDIRECT_HTML.format("latest/userguides/quickstart.html")
         assert builder.index_file.read_text() == expected_content
 
         # Ensure static content exists.
@@ -72,7 +95,7 @@ def test_build_release(self, mock_sphinx, mock_git, temp_path):
         assert_build_path(call_path.parent / "stable", "stable")
         # Ensure re-direct exists and points to stable/.
         assert builder.index_file.is_file()
-        expected_content = REDIRECT_HTML.format("stable")
+        expected_content = REDIRECT_HTML.format("stable/")
         assert builder.index_file.read_text() == expected_content
 
     @pytest.mark.parametrize("sub_tag", ("alpha", "beta"))