Support index.md auto-discovery in repo namespace

Author: pedro-psb

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"},

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,39 +108,61 @@ 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
                 if repo_nav:
                     _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:

staging_docs/dev/guides/.gitkeep

@@ -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
+    ```