From 607fe970b7fc8877b19878570642cc8efab55f3c Mon Sep 17 00:00:00 2001 From: Juliya Smith Date: Thu, 3 Oct 2024 12:07:34 -0600 Subject: [PATCH] fix: quickstart --- README.md | 2 +- sphinx_ape/_base.py | 31 ++++++++++++++++++++++--------- sphinx_ape/_cli.py | 2 +- sphinx_ape/build.py | 11 ++++++++--- tests/test_build.py | 27 +++++++++++++++++++++++++-- 5 files changed, 57 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index cb2e36d..916704a 100644 --- 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 index efe7d58..77c4045 100644 --- 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 index bcecc74..a1f7f9a 100644 --- 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 index 9009767..6783c03 100644 --- a/sphinx_ape/build.py +++ b/sphinx_ape/build.py @@ -12,7 +12,7 @@ Redirecting... - + """ @@ -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 index dd99cb2..21d5ed7 100644 --- 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"))