From be65ca3a021c3978a7a771f2e21ed77b3efd9aed Mon Sep 17 00:00:00 2001 From: Julian Risch Date: Fri, 20 Jun 2025 11:53:39 +0200 Subject: [PATCH 1/3] feat: Add Docusaurus renderer --- src/haystack_pydoc_tools/renderers.py | 58 +++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/src/haystack_pydoc_tools/renderers.py b/src/haystack_pydoc_tools/renderers.py index 5cca14b..76b96fd 100644 --- a/src/haystack_pydoc_tools/renderers.py +++ b/src/haystack_pydoc_tools/renderers.py @@ -26,6 +26,14 @@ """ +DOCUSAURUS_FRONTMATTER = """--- +title: {title} +id: {id} +description: {description} +--- + +""" + def create_headers(version: str): # Utility function to create Readme.io headers. @@ -210,3 +218,53 @@ def _doc_version(self) -> str: major, minor = latest_version.major, latest_version.minor return f"v{major}.{minor}" + +@dataclasses.dataclass +class DocusaurusRenderer(Renderer): + """ + This custom Renderer is heavily based on the `MarkdownRenderer`, + it just prepends a front matter so that the output can be published + directly to docusaurus. + """ + + # These settings will be used in the front matter output + title: str + id: str + description: str + + # This exposes a special `markdown` settings value that can be used to pass + # parameters to the underlying `MarkdownRenderer` + markdown: MarkdownRenderer = dataclasses.field(default_factory=MarkdownRenderer) + + def init(self, context: Context) -> None: + self.markdown.init(context) + self.version = os.environ.get("PYDOC_TOOLS_HAYSTACK_DOC_VERSION", self._doc_version()) + + def _doc_version(self) -> str: + """ + Returns the docs version. + """ + # We're assuming hatch is installed and working + res = subprocess.run(["hatch", "version"], capture_output=True, check=True) + res.check_returncode() + full_version = res.stdout.decode().strip() + major, minor = full_version.split(".")[:2] + if "rc0" in full_version: + return f"v{major}.{minor}-unstable" + return f"v{major}.{minor}" + + def render(self, modules: t.List[docspec.Module]) -> None: + if self.markdown.filename is None: + sys.stdout.write(self._frontmatter()) + self.markdown.render_single_page(sys.stdout, modules) + else: + with open(self.markdown.filename, "w", encoding=self.markdown.encoding) as fp: + fp.write(self._frontmatter()) + self.markdown.render_single_page(t.cast(t.TextIO, fp), modules) + + def _frontmatter(self) -> str: + return DOCUSAURUS_FRONTMATTER.format( + title=self.title, + id=self.id, + description=self.description, + ) From 8b6fbf1a942ba576f89323783e500951cb0d90c5 Mon Sep 17 00:00:00 2001 From: Julian Risch Date: Fri, 20 Jun 2025 12:00:35 +0200 Subject: [PATCH 2/3] use slug as id --- src/haystack_pydoc_tools/renderers.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/haystack_pydoc_tools/renderers.py b/src/haystack_pydoc_tools/renderers.py index 76b96fd..6c82e45 100644 --- a/src/haystack_pydoc_tools/renderers.py +++ b/src/haystack_pydoc_tools/renderers.py @@ -28,7 +28,7 @@ DOCUSAURUS_FRONTMATTER = """--- title: {title} -id: {id} +id: {slug} description: {description} --- @@ -265,6 +265,6 @@ def render(self, modules: t.List[docspec.Module]) -> None: def _frontmatter(self) -> str: return DOCUSAURUS_FRONTMATTER.format( title=self.title, - id=self.id, + slug=self.slug, description=self.description, ) From f43bd1e7ed2419f50e49ca7f5070c39a7b944d0b Mon Sep 17 00:00:00 2001 From: Julian Risch Date: Fri, 20 Jun 2025 12:10:45 +0200 Subject: [PATCH 3/3] replace slug with id --- src/haystack_pydoc_tools/renderers.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/haystack_pydoc_tools/renderers.py b/src/haystack_pydoc_tools/renderers.py index 6c82e45..76b96fd 100644 --- a/src/haystack_pydoc_tools/renderers.py +++ b/src/haystack_pydoc_tools/renderers.py @@ -28,7 +28,7 @@ DOCUSAURUS_FRONTMATTER = """--- title: {title} -id: {slug} +id: {id} description: {description} --- @@ -265,6 +265,6 @@ def render(self, modules: t.List[docspec.Module]) -> None: def _frontmatter(self) -> str: return DOCUSAURUS_FRONTMATTER.format( title=self.title, - slug=self.slug, + id=self.id, description=self.description, )