From 11ea5f19915b2b4c39224426e763f2a66ed94ece Mon Sep 17 00:00:00 2001 From: Pedro Brochado Date: Thu, 22 Feb 2024 14:33:15 -0300 Subject: [PATCH] Support index.md auto-discovery in repo namespace --- src/pulp_docs/navigation.py | 11 ++++- src/pulp_docs/utils/aggregation.py | 63 +++++++++++++++++------- staging_docs/dev/guides/.gitkeep | 0 staging_docs/dev/index.md | 39 +++++++++++++++ staging_docs/dev/learn/.gitkeep | 0 staging_docs/dev/tutorials/.gitkeep | 0 staging_docs/dev/tutorials/quickstart.md | 3 -- 7 files changed, 93 insertions(+), 23 deletions(-) create mode 100644 staging_docs/dev/guides/.gitkeep create mode 100644 staging_docs/dev/index.md create mode 100644 staging_docs/dev/learn/.gitkeep create mode 100644 staging_docs/dev/tutorials/.gitkeep delete mode 100644 staging_docs/dev/tutorials/quickstart.md diff --git a/src/pulp_docs/navigation.py b/src/pulp_docs/navigation.py index 7b8c432..bebc2fc 100644 --- a/src/pulp_docs/navigation.py +++ b/src/pulp_docs/navigation.py @@ -118,12 +118,19 @@ def grouped_by_persona(tmpdir: Path, repos: Repos): ] }, { - "Plugins": f.repo_grouping( "{repo}/docs/dev/{content}", repo_types=["content"] ) }, + "Plugins": f.repo_grouping( + "{repo}/docs/dev/{content}", repo_types=["content"] + ) + }, {"Extras": f.repo_grouping("{repo}/docs/dev/{content}", repo_types=["other"])}, ] help_section = [ *f.get_children("pulp-docs/docs/sections/help/community"), - {"Documentation Usage": f.get_children("pulp-docs/docs/sections/help/using-this-doc")}, + { + "Documentation Usage": f.get_children( + "pulp-docs/docs/sections/help/using-this-doc" + ) + }, { "Changelogs": [ {"Pulpcore": "pulpcore/changes/changelog.md"}, diff --git a/src/pulp_docs/utils/aggregation.py b/src/pulp_docs/utils/aggregation.py index 3f69a40..c9f8f4c 100644 --- a/src/pulp_docs/utils/aggregation.py +++ b/src/pulp_docs/utils/aggregation.py @@ -1,7 +1,7 @@ import os +import re import typing as t from pathlib import Path -import re from pulp_docs.constants import Names from pulp_docs.repository import Repos @@ -94,7 +94,12 @@ def repo_grouping( # Selected a set of repos selected_repos = [] - selected_content = content_types or ["tutorials", "guides", "learn", "reference"] + selected_content = content_types or [ + "tutorials", + "guides", + "learn", + "reference", + ] if not repo_types: # default case selected_repos = self.repos.all else: @@ -103,32 +108,32 @@ def repo_grouping( # Dont expand content-types if not _expand_content_types: for repo in selected_repos: - lookup_path = self.tmpdir / template_str.format( - repo=repo.name, admin=Names.ADMIN, user=Names.USER - ) + lookup_path = self._parse_template_str(template_str, repo.name) _repo_content = self.get_children(lookup_path) if _repo_content: - _nav[repo.title] = _repo_content if len(_repo_content) > 1 else _repo_content[0] + _nav[repo.title] = ( + _repo_content if len(_repo_content) > 1 else _repo_content[0] + ) # Expand content-types else: for repo in selected_repos: repo_nav = {} + # Include index.md if present in staging_docs/{persona}/index.md + persona_basepath = self._parse_template_str( + template_str, repo.name, "placeholder" + ).parent + index_path = persona_basepath / "index.md" + if index_path.exists(): + repo_nav["Overview"] = str(index_path.relative_to(self.tmpdir)) + for content_type in selected_content: - lookup_path = self.tmpdir / template_str.format( - repo=repo.name, - admin=Names.ADMIN, - user=Names.USER, - content=content_type, + # Get repo files from content-type and persona + lookup_path = self._parse_template_str( + template_str, repo.name, content_type ) _repo_content = self.get_children(lookup_path) - # special treatment to quickstart tutorial - if content_type.lower() == "tutorials": - quickstart_file = self._pop_quickstart_from(_repo_content) - if quickstart_file: - repo_nav["Quickstart"] = quickstart_file # type: ignore - - # doesnt render content-type section if no files inside + # Prevent rendering content-type section if there are no files if _repo_content: content_type_name = Names.get(content_type) repo_nav[content_type_name] = _repo_content # type: ignore @@ -136,6 +141,28 @@ def repo_grouping( _nav[repo.title] = repo_nav return _nav or ["#"] + def _parse_template_str( + self, template_str: str, repo_name: str, content_type: t.Optional[str] = None + ) -> Path: + """ + Replace template_str with repo_name and content_type. + + Additionally, normalized {admin} {user} and {dev} names: + - {repo}/docs/dev/{content} + - {repo}/docs/{admin}/{content} -> uses constant for {admin} + + TODO: deprecate this method of template string and use dataclasses instead. + """ + kwargs = { + "repo": repo_name, + "admin": Names.ADMIN, + "user": Names.USER, + } + if content_type: + kwargs["content"] = content_type + + return self.tmpdir / template_str.format(**kwargs) + def _pop_quickstart_from(self, pathlist: t.List[str]) -> t.Optional[str]: """Get quickstart.md file from filelist with case and variations tolerance""" for path in pathlist: diff --git a/staging_docs/dev/guides/.gitkeep b/staging_docs/dev/guides/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/staging_docs/dev/index.md b/staging_docs/dev/index.md new file mode 100644 index 0000000..fd2c691 --- /dev/null +++ b/staging_docs/dev/index.md @@ -0,0 +1,39 @@ +# Overview + +## What it is + +`pulp-docs` is a tool for serving and building an unified doc out of Pulp's Plugin Ecosystem. + +The idea is that each repository should install `pulp-docs` and imediatelly be able run the unified website server. +Also, this should be used for the production build. + +It was developed as part of [The new Pulp "Unified Docs"](https://hackmd.io/eE3kG8qhT9eohRYbtooNww?view) project. + +## How it works + +Through a `mkdocs-macro-plugin` hook (called in early stages of mkdocs processing), we inject the following steps: + +1. Read [`repolist.yml`](https://github.com/pedro-psb/pulp-docs/blob/main/src/pulp_docs/data/repolist.yml) packaged with `pulp-docs` to know which repos/urls to use +1. Download and Place all source code required to dir under `tempfile.gettempdir()` + - Uses `../{repo}` if available OR + - Uses existing cached `{tmpdir}/{repo}` if available OR + - Downloads from github +1. Configure `mkdocs` through a hook: fix `mkdocstrings` config, generate navigation structure, etc + +## Quickstart + +Recommended way for daily usage: + +=== "pipx" + + ```bash + pipx install git+https://github.com/pedro-psb/pulp-docs --include-deps + pulp-docs serve + ``` + +=== "pip" + + ```bash + pip --user install git+https://github.com/pedro-psb/pulp-docs + pulp-docs serve + ``` diff --git a/staging_docs/dev/learn/.gitkeep b/staging_docs/dev/learn/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/staging_docs/dev/tutorials/.gitkeep b/staging_docs/dev/tutorials/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/staging_docs/dev/tutorials/quickstart.md b/staging_docs/dev/tutorials/quickstart.md deleted file mode 100644 index 412701a..0000000 --- a/staging_docs/dev/tutorials/quickstart.md +++ /dev/null @@ -1,3 +0,0 @@ -# Quickstart - -Learn how to use `pulp-docs`