diff --git a/.github/utils/pydoc-markdown.sh b/.github/utils/pydoc-markdown.sh index 4322da034e..670bd09697 100755 --- a/.github/utils/pydoc-markdown.sh +++ b/.github/utils/pydoc-markdown.sh @@ -1,7 +1,6 @@ #!/bin/bash set -e # Fails on any error in the following loop -export PYTHONPATH=$PWD/docs/pydoc # Make the renderers available to pydoc cd docs/pydoc rm -rf temp && mkdir temp cd temp diff --git a/.github/workflows/readme_sync.yml b/.github/workflows/readme_sync.yml index c66dedb24b..4f245adf32 100644 --- a/.github/workflows/readme_sync.yml +++ b/.github/workflows/readme_sync.yml @@ -23,7 +23,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install -r docs/pydoc/requirements.txt + pip install -U haystack-pydoc-tools - name: Generate API docs env: @@ -41,4 +41,4 @@ jobs: env: README_API_KEY: ${{ secrets.README_API_KEY }} with: - rdme: docs ./docs/pydoc/temp --key="$README_API_KEY" --version=2.0 \ No newline at end of file + rdme: docs ./docs/pydoc/temp --key="$README_API_KEY" --version=2.0 diff --git a/docs/pydoc/__init__.py b/docs/pydoc/__init__.py deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/pydoc/config/builder.yml b/docs/pydoc/config/builder.yml index 5596240419..50b40bc85d 100644 --- a/docs/pydoc/config/builder.yml +++ b/docs/pydoc/config/builder.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/builders] modules: ["answer_builder", "prompt_builder", "dynamic_prompt_builder", "dynamic_chat_prompt_builder"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Extract the output of a Generator to an Answer format, and build prompts. category_slug: haystack-classes title: Builder API diff --git a/docs/pydoc/config/caching.yml b/docs/pydoc/config/caching.yml index f116f92b2e..b1e27cbb3d 100644 --- a/docs/pydoc/config/caching.yml +++ b/docs/pydoc/config/caching.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/caching] modules: ["cache_checker"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Checks if any document coming from the given URL is already present in the store. category_slug: haystack-classes title: CacheChecker API diff --git a/docs/pydoc/config/classifier.yml b/docs/pydoc/config/classifier.yml index 1789b017c0..93b72dc8f7 100644 --- a/docs/pydoc/config/classifier.yml +++ b/docs/pydoc/config/classifier.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/classifiers] modules: ["document_language_classifier"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Detects the language of the Documents and routes them appropriately. category_slug: haystack-classes title: Classifier API diff --git a/docs/pydoc/config/converter.yml b/docs/pydoc/config/converter.yml index 5c3e09c640..f3a7a52a18 100644 --- a/docs/pydoc/config/converter.yml +++ b/docs/pydoc/config/converter.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/converters] modules: ["azure", "html", "markdown", "pypdf", "tika", "txt"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Extracts text from files in different formats and converts it into a unified Document format. category_slug: haystack-classes title: Converter API diff --git a/docs/pydoc/config/dataclass.yml b/docs/pydoc/config/dataclass.yml index 9b9c3a21cb..126c7daf62 100644 --- a/docs/pydoc/config/dataclass.yml +++ b/docs/pydoc/config/dataclass.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/dataclasses] modules: ["answer", "byte_stream", "chat_message", "document", "streaming_chunk"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Core classes that carry data through the system. category_slug: haystack-classes title: Data Classes API diff --git a/docs/pydoc/config/document_store.yml b/docs/pydoc/config/document_store.yml index 7901a46227..5505adab1f 100644 --- a/docs/pydoc/config/document_store.yml +++ b/docs/pydoc/config/document_store.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/document_stores/in_memory] modules: ["document_store"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Stores your texts and meta data and provides them to the Retriever at query time. category_slug: haystack-classes title: DocumentStore API diff --git a/docs/pydoc/config/embedder.yml b/docs/pydoc/config/embedder.yml index 6e74439f52..432c89a045 100644 --- a/docs/pydoc/config/embedder.yml +++ b/docs/pydoc/config/embedder.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/embedders] modules: [ @@ -22,7 +22,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Transforms queries into vectors to look for similar or relevant Documents. category_slug: haystack-classes title: Embedder API diff --git a/docs/pydoc/config/extractor.yml b/docs/pydoc/config/extractor.yml index 3caed61499..f17e64bc9e 100644 --- a/docs/pydoc/config/extractor.yml +++ b/docs/pydoc/config/extractor.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/extractors] modules: ["named_entity_extractor"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Extracts predefined entities out of a piece of text. category_slug: haystack-classes title: Extractor API diff --git a/docs/pydoc/config/fetcher.yml b/docs/pydoc/config/fetcher.yml index be6f100d87..e480e61f00 100644 --- a/docs/pydoc/config/fetcher.yml +++ b/docs/pydoc/config/fetcher.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/fetchers] modules: ["link_content"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Fetches content from a list of URLs and returns a list of extracted content streams. category_slug: haystack-classes title: LinkContentFetcher API diff --git a/docs/pydoc/config/generator.yml b/docs/pydoc/config/generator.yml index 3a2a678063..1f0bb79fac 100644 --- a/docs/pydoc/config/generator.yml +++ b/docs/pydoc/config/generator.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/generators] modules: [ @@ -22,7 +22,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Enables text generation using LLMs. category_slug: haystack-classes title: Generator API diff --git a/docs/pydoc/config/joiner.yml b/docs/pydoc/config/joiner.yml index 2ec25c1ff7..2b062f3f79 100644 --- a/docs/pydoc/config/joiner.yml +++ b/docs/pydoc/config/joiner.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/joiners] modules: ["document_joiner"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Routes data to the right component based on its file type or metadata. category_slug: haystack-classes title: Joiner API diff --git a/docs/pydoc/config/others.yml b/docs/pydoc/config/others.yml index 88b8bfb60e..ff51ff586c 100644 --- a/docs/pydoc/config/others.yml +++ b/docs/pydoc/config/others.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/others] modules: ["multiplexer"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Other utility components for Haystack Pipelines. category_slug: haystack-classes title: Other Components API diff --git a/docs/pydoc/config/pipeline.yml b/docs/pydoc/config/pipeline.yml index c9a1b9b185..687354d99c 100644 --- a/docs/pydoc/config/pipeline.yml +++ b/docs/pydoc/config/pipeline.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack] modules: ["pipeline"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Arranges components and integrations in flow. category_slug: haystack-classes title: Pipelines API diff --git a/docs/pydoc/config/preprocessor.yml b/docs/pydoc/config/preprocessor.yml index 436d2f5906..6736ef0c82 100644 --- a/docs/pydoc/config/preprocessor.yml +++ b/docs/pydoc/config/preprocessor.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/preprocessors] modules: ["document_cleaner", "document_splitter"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Normalizes white spaces, gets rid of headers and footers, cleans empty lines in your Documents, or splits them into smaller pieces. category_slug: haystack-classes title: PreProcessor API diff --git a/docs/pydoc/config/ranker.yml b/docs/pydoc/config/ranker.yml index 96a39c2f86..ec9ca5417c 100644 --- a/docs/pydoc/config/ranker.yml +++ b/docs/pydoc/config/ranker.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/rankers] modules: ["meta_field", "transformers_similarity"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Reorders a set of Documents based on their relevance to the query. category_slug: haystack-classes title: Ranker API diff --git a/docs/pydoc/config/reader.yml b/docs/pydoc/config/reader.yml index d130aca0a1..449ceded6a 100644 --- a/docs/pydoc/config/reader.yml +++ b/docs/pydoc/config/reader.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/readers] modules: ["extractive"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Takes a query and a set of Documents as input and returns ExtractedAnswers by selecting a text span within the Documents. category_slug: haystack-classes title: Reader API diff --git a/docs/pydoc/config/retriever.yml b/docs/pydoc/config/retriever.yml index d8c47ab443..0eb92f6f27 100644 --- a/docs/pydoc/config/retriever.yml +++ b/docs/pydoc/config/retriever.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/retrievers/in_memory] modules: ["bm25_retriever", "embedding_retriever"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Sweeps through a Document Store and returns a set of candidate Documents that are relevant to the query. category_slug: haystack-classes title: Retriever API diff --git a/docs/pydoc/config/router.yml b/docs/pydoc/config/router.yml index bac0d1cae9..772f4d5b86 100644 --- a/docs/pydoc/config/router.yml +++ b/docs/pydoc/config/router.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/routers] modules: ["conditional_router", "file_type_router", "metadata_router", "text_language_router"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Routes data to the right component based on its file type or metadata. category_slug: haystack-classes title: Router API diff --git a/docs/pydoc/config/sampler.yml b/docs/pydoc/config/sampler.yml index d9e0330510..4e0c145989 100644 --- a/docs/pydoc/config/sampler.yml +++ b/docs/pydoc/config/sampler.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/samplers] modules: ["top_p"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Filters documents based on their similarity scores using top-p sampling. category_slug: haystack-classes title: TopPSampler API diff --git a/docs/pydoc/config/websearch.yml b/docs/pydoc/config/websearch.yml index deb257bcb6..2778ff202c 100644 --- a/docs/pydoc/config/websearch.yml +++ b/docs/pydoc/config/websearch.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/websearch] modules: ["serper_dev"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Web search engine for Haystack. category_slug: haystack-classes title: Websearch API diff --git a/docs/pydoc/config/whisper.yml b/docs/pydoc/config/whisper.yml index 3a6bf91907..6c02d46d44 100644 --- a/docs/pydoc/config/whisper.yml +++ b/docs/pydoc/config/whisper.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/audio] modules: ["whisper_local", "whisper_remote"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Transcribes audio files. category_slug: haystack-classes title: WhisperTranscriber API diff --git a/docs/pydoc/config/writer.yml b/docs/pydoc/config/writer.yml index 20f63b13c6..0737b7ec5b 100644 --- a/docs/pydoc/config/writer.yml +++ b/docs/pydoc/config/writer.yml @@ -1,5 +1,5 @@ loaders: - - type: loaders.CustomPythonLoader + - type: haystack_pydoc_tools.loaders.CustomPythonLoader search_path: [../../../haystack/components/writers] modules: ["document_writer"] ignore_when_discovered: ["__init__"] @@ -12,7 +12,7 @@ processors: - type: smart - type: crossref renderer: - type: renderers.ReadmePreviewRenderer + type: haystack_pydoc_tools.renderers.ReadmePreviewRenderer excerpt: Writes Documents to a DocumentStore. category_slug: haystack-classes title: DocumentWriter API diff --git a/docs/pydoc/loaders.py b/docs/pydoc/loaders.py deleted file mode 100644 index 0df8344cd3..0000000000 --- a/docs/pydoc/loaders.py +++ /dev/null @@ -1,63 +0,0 @@ -import copy -import typing as t - -import docspec -from pydoc_markdown.interfaces import Context -from pydoc_markdown.contrib.loaders.python import PythonLoader - - -class CustomPythonLoader(PythonLoader): - def load(self) -> t.Iterable[docspec.Module]: - """ - Load the modules, but include inherited methods in the classes. - """ - # Load all haystack modules - temp_loader = PythonLoader(search_path=["../../../haystack"]) - temp_loader.init(Context(directory=".")) - all_modules = list(temp_loader.load()) - - # Collect all classes - classes = {} - for module in all_modules: - for member in module.members: - if isinstance(member, docspec.Class): - classes[member.name] = member - - # Load the modules specified in the search path - modules = super().load() - - # Add inherited methods to the classes - modules = self.include_inherited_methods(modules, classes) - - return modules - - def include_inherited_methods( - self, modules: t.Iterable[docspec.Module], classes: t.Dict[str, docspec.Class] - ) -> t.Iterable[docspec.Module]: - """ - Recursively include inherited methods from the base classes. - """ - modules = list(modules) - for module in modules: - for cls in module.members: - if isinstance(cls, docspec.Class): - self.include_methods_for_class(cls, classes) - - return modules - - def include_methods_for_class(self, cls: docspec.Class, classes: t.Dict[str, docspec.Class]): - """ - Include all methods inherited from base classes to the class. - """ - if cls.bases is None: - return - for base in cls.bases: - if base in classes: - base_cls = classes[base] - self.include_methods_for_class(base_cls, classes) - - for member in base_cls.members: - if isinstance(member, docspec.Function) and not any(m.name == member.name for m in cls.members): - new_member = copy.deepcopy(member) - new_member.parent = cls - cls.members.append(new_member) diff --git a/docs/pydoc/renderers.py b/docs/pydoc/renderers.py deleted file mode 100644 index 6450f666cb..0000000000 --- a/docs/pydoc/renderers.py +++ /dev/null @@ -1,148 +0,0 @@ -import os -import sys -import io -import dataclasses -import typing as t -import base64 -import warnings -from pathlib import Path - -import requests -import docspec -from pydoc_markdown.interfaces import Context, Renderer -from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer - - -README_FRONTMATTER = """--- -title: {title} -excerpt: {excerpt} -category: {category} -slug: {slug} -parentDoc: {parent_doc} -order: {order} -hidden: false ---- - -""" - - -def create_headers(version: str): - # Utility function to create Readme.io headers. - # We assume the README_API_KEY env var is set since we check outside - # to show clearer error messages. - README_API_KEY = os.getenv("README_API_KEY") - token = base64.b64encode(f"{README_API_KEY}:".encode()).decode() - return {"authorization": f"Basic {token}", "x-readme-version": version} - - -@dataclasses.dataclass -class ReadmeRenderer(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 readme.io. - """ - - # These settings will be used in the front matter output - title: str - category_slug: str - excerpt: str - slug: str - order: int - parent_doc_slug: str = "" - # Docs categories fetched from Readme.io - categories: t.Dict[str, str] = dataclasses.field(init=False) - # 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 = self._doc_version() - self.categories = self._readme_categories(self.version) - - def _doc_version(self) -> str: - """ - Returns the docs version. - """ - root = Path(__file__).absolute().parent.parent.parent - full_version = (root / "VERSION.txt").read_text() - major, minor = full_version.split(".")[:2] - if "rc0" in full_version: - return f"v{major}.{minor}-unstable" - return f"v{major}.{minor}" - - def _readme_categories(self, version: str) -> t.Dict[str, str]: - """ - Fetch the categories of the given version from Readme.io. - README_API_KEY env var must be set to correctly get the categories. - Returns dictionary containing all the categories slugs and their ids. - """ - README_API_KEY = os.getenv("README_API_KEY") - if not README_API_KEY: - warnings.warn("README_API_KEY env var is not set, using a placeholder category ID") - return {"haystack-classes": "ID"} - - headers = create_headers(version) - - res = requests.get("https://dash.readme.com/api/v1/categories", headers=headers, timeout=60) - - if not res.ok: - sys.exit(f"Error requesting {version} categories") - - return {c["slug"]: c["id"] for c in res.json()} - - def _doc_id(self, doc_slug: str, version: str) -> str: - """ - Fetch the doc id of the given doc slug and version from Readme.io. - README_API_KEY env var must be set to correctly get the id. - If doc_slug is an empty string return an empty string. - """ - if not doc_slug: - # Not all docs have a parent doc, in case we get no slug - # we just return an empty string. - return "" - - README_API_KEY = os.getenv("README_API_KEY") - if not README_API_KEY: - warnings.warn("README_API_KEY env var is not set, using a placeholder doc ID") - return "fake-doc-id" - - headers = create_headers(version) - res = requests.get(f"https://dash.readme.com/api/v1/docs/{doc_slug}", headers=headers, timeout=60) - if not res.ok: - sys.exit(f"Error requesting {doc_slug} doc for version {version}") - - return res.json()["id"] - - 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 io.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 README_FRONTMATTER.format( - title=self.title, - category=self.categories[self.category_slug], - parent_doc=self._doc_id(self.parent_doc_slug, self.version), - excerpt=self.excerpt, - slug=self.slug, - order=self.order, - ) - - -@dataclasses.dataclass -class ReadmePreviewRenderer(ReadmeRenderer): - """ - This custom Renderer behaves just like the ReadmeRenderer but renders docs with the hardcoded version 2.0 to generate correct category ids. - """ - - def _doc_version(self) -> str: - """ - Returns the hardcoded docs version 2.0. - """ - return "v2.0" diff --git a/docs/pydoc/requirements.txt b/docs/pydoc/requirements.txt deleted file mode 100644 index 5c14700f58..0000000000 --- a/docs/pydoc/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -pydoc-markdown==4.8.2