Reorganize Reference section

Author: pedro-psb

src/pulp_docs/mkdocs_macros.py

@@ -101,7 +101,7 @@ def prepare_repositories(TMPDIR: Path, repos: Repos, config: Config):
             this_src_dir = repo_sources / repo_or_pkg.subpackage_of / repo_or_pkg.name
 
         # install and post-process
-        _install_doc_files(this_src_dir, this_docs_dir, repo_or_pkg)
+        _place_doc_files(this_src_dir, this_docs_dir, repo_or_pkg)
         if repo_or_pkg.type == "content":
             _generate_rest_api_page(this_docs_dir, repo_or_pkg.name, repo_or_pkg.title)
 
@@ -122,7 +122,7 @@ def prepare_repositories(TMPDIR: Path, repos: Repos, config: Config):
     return (repo_docs, repo_sources)
 
 
-def _install_doc_files(src_dir: Path, docs_dir: Path, repo: Repo):
+def _place_doc_files(src_dir: Path, docs_dir: Path, repo: Repo):
     """Copy only doc-related files from src_dir to doc_dir"""
     log.info(f"Moving doc files:\nfrom '{src_dir}'\nto '{docs_dir}'")
 
@@ -131,15 +131,18 @@ def _install_doc_files(src_dir: Path, docs_dir: Path, repo: Repo):
     except FileNotFoundError:
         Path(docs_dir / "docs").mkdir(parents=True)
         repo.status.has_staging_docs = False
-    try:
-        shutil.copy(src_dir / "CHANGELOG.md", docs_dir / "CHANGELOG.md")
-    except FileNotFoundError:
-        repo.status.has_changelog = False
 
-    try:
-        shutil.copy(src_dir / "README.md", docs_dir / "README.md")
-    except FileNotFoundError:
-        repo.status.has_readme = False
+    # Get CHANGELOG
+    # TODO: remove reading .rst (plugins should provide markdown CHANGELOG)
+    repo.status.has_changelog = False
+    for changelog_name in ("CHANGELOG.md", "CHANGES.md", "CHANGES.rst"):
+        changelog_path = Path(src_dir / changelog_name)
+        if changelog_path.exists():
+            reference_dir = Path(docs_dir / "docs/reference")
+            reference_dir.mkdir(exist_ok=True)
+            shutil.copy(changelog_path, reference_dir / "CHANGELOG.md")
+            repo.status.has_changelog = True
+            break
 
 
 def _generate_rest_api_page(docs_dir: Path, repo_name: str, repo_title: str):
@@ -243,8 +246,15 @@ def define_env(env):
 
     log.info("[pulp-docs] Done with pulp-docs.")
     env.conf["pulp_repos"] = repos
+    env.config["pulp_repos"] = repos
     env.conf["pulp_config"] = config
 
+    # Extra config
+    @env.macro
+    def get_repos(repo_type="content"):
+        "Return repo names by type"
+        return sorted(repos.get_repos(repo_types=[repo_type]), key=lambda x: x.title)
+
 
 def on_pre_page_macros(env):
     """The mkdocs-macros hook just before an inidvidual page render."""

src/pulp_docs/navigation.py

@@ -134,9 +134,11 @@ def grouped_by_persona(tmpdir: Path, repos: Repos):
     ]
     reference_section = [
         {"Overview": f.section_file("reference/index.md")},
-        {"Repository Map": f.section_file("reference/01-repository-map.md")},
+        {"Rest API": "pulp-docs/docs/rest_api.md"},
         {"Glossary": f.section_file("reference/02-glossary.md")},
-        {"Repositories": f.repo_reference_grouping()},
+        {"Pulpcore": f.section(Names.CORE, f.get_children, "pulpcore/docs/reference")},
+        {"Plugins": f.repo_grouping("{repo}/docs/reference", repo_types=["content"])},
+        {"Extra": f.repo_grouping("{repo}/docs/reference", repo_types=["other"])},
     ]
 
     # Main Section

src/pulp_docs/utils/aggregation.py

@@ -1,6 +1,7 @@
 import os
 import typing as t
 from pathlib import Path
+import re
 
 from pulp_docs.constants import Names
 from pulp_docs.repository import Repos

staging_docs/rest_api.md

@@ -0,0 +1,11 @@
+# Rest API
+
+The REST API reference for Pulp Plugins is generated using [ReDoc](https://redocly.com/redoc/) and are published in standalone pages:
+
+<div class="grid cards" markdown>
+
+{% for repo in get_repos() %}
+- <a href="https://docs.pulpproject.org/{{ repo.name }}/restapi.html" target="_blank">{{ repo.title }}</a>
+{% endfor %}
+
+</div>