Make the section-pages URLs cleaner and repo-independent

Author: pedro-psb

src/pulp_docs/constants.py

@@ -1,3 +1,8 @@
+"""Project constants."""
+
+SECTION_REPO = "pulp-docs"
+"""The repository which contains section pages"""
+
 ADMIN_NAME = "admin"
 USER_NAME = "user"
 RESTAPI_URL_TEMPLATE = "https://docs.pulpproject.org/{}/restapi.html"

src/pulp_docs/mkdocs_macros.py

@@ -28,6 +28,7 @@
 
 from pulp_docs.cli import Config
 from pulp_docs.navigation import get_navigation
+from pulp_docs.constants import SECTION_REPO
 from pulp_docs.repository import Repo, Repos, SubPackage
 from pulp_docs.utils.general import get_git_ignored_files
 
@@ -165,6 +166,8 @@ def _place_doc_files(src_dir: Path, docs_dir: Path, repo: Repo, api_src_dir: Pat
     """
     Copy only doc-related files from src_dir to doc_dir.
 
+    This effectively make it possible to control the url design.
+
     Examples:
         ```
         # src_dir
@@ -188,6 +191,13 @@ def _place_doc_files(src_dir: Path, docs_dir: Path, repo: Repo, api_src_dir: Pat
         Path(docs_dir / "docs").mkdir(parents=True)
         repo.status.has_staging_docs = False
 
+    # Setup section pages (for better urls)
+    if repo.name == SECTION_REPO:
+        shutil.copytree(
+            docs_dir / "docs" / "sections", docs_dir.parent, dirs_exist_ok=True
+        )
+        shutil.rmtree(docs_dir / "docs" / "sections")
+
     # Setup rest Api
     if has_restapi(repo):
         api_json = api_src_dir / f"{repo.name}/api.json"

src/pulp_docs/navigation.py

@@ -28,9 +28,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import List
 
-from pulp_docs.constants import Names
 from pulp_docs.repository import Repos
 from pulp_docs.utils.aggregation import AgregationUtils
 
@@ -58,82 +56,32 @@ def grouped_by_persona(tmpdir: Path, repos: Repos):
                     {content-type}
     """
     f = AgregationUtils(tmpdir, repos)
-    SECTION_HOST = "pulp-docs"
 
     # Manual section for each persona
     TEMPLATE_STR = "{repo}/docs/{persona}/{content}"
     manual_nav = {
         "user": [
-            {"Overview": f"{SECTION_HOST}/docs/sections/user/index.md"},
-            *f.repo_grouping(TEMPLATE_STR, personas=["user", "admin"])
+            {"Overview": "user/index.md"},
+            *f.repo_grouping(TEMPLATE_STR, personas=["user", "admin"]),
         ],
         "dev": [
-            {"Overview": f"{SECTION_HOST}/docs/sections/dev/index.md"},
-            *f.repo_grouping(TEMPLATE_STR, personas=["dev"])
+            {"Overview": "dev/index.md"},
+            *f.repo_grouping(TEMPLATE_STR, personas=["dev"]),
         ],
     }
 
     # Custom help section
     help_section = [
-        {"Overview": f"{SECTION_HOST}/docs/sections/help/index.md"},
-        {"Community": f"{SECTION_HOST}/docs/sections/help/community/"},
-        {"More": f"{SECTION_HOST}/docs/sections/help/more/"},
+        {"Overview": "help/index.md"},
+        {"Community": "help/community/"},
+        {"More": "help/more/"},
     ]
 
-    # Main Section
-    # pulpcore_nav = manual_nav["user"][1]["Core"][0]
-    # pulpcore_nav = create_repo_toc_index(pulpcore_nav)
-    # print(pulpcore_nav)
-    # manual_nav["user"][1]["Core"][0] = pulpcore_nav
-
     navigation = [
         {"Home": "index.md"},
         {"User Manual": manual_nav["user"]},
         {"Developer Manual": manual_nav["dev"]},
-        {"Blog": ["pulp-docs/docs/sections/blog/index.md"]},
+        {"Blog": ["blog/index.md"]},
         {"Help": help_section},
     ]
     return navigation
-
-
-def create_repo_toc_index(repo_nav: List[dict]):
-    """
-    TODO: maybe try to leverage site-map
-
-    Create a toc with the format: {tuple-path: file-path}
-
-    Sample input:
-        {'Pulp Core': [{'User': [{'Tutorials': 'pulpcore/docs/user/tutorials/'},
-                             {'How-to Guides': 'pulpcore/docs/user/guides/'},
-                             {'Learn More': 'pulpcore/docs/user/learn/'}]},
-                   {'Admin': [{'How-to Guides': 'pulpcore/docs/admin/guides/'},
-                              {'Learn More': 'pulpcore/docs/admin/learn/'}]},
-                   {'REST API': 'pulpcore/restapi.md'},
-                   {'Changelog': 'pulpcore/changes.md'}]}
-    """
-
-    def is_nav(item):
-        return isinstance(item, list)
-
-    # {dir-path: page-str}
-    toc = {}
-    path = []
-
-    def recursive_add(nav):
-        for name, item in nav.items():
-            path.append(name)
-            if isinstance(item, list):
-                for entry in item:
-                    recursive_add(entry)
-                    path.pop()
-            elif isinstance(item, dict):
-                item_name, entry = item.items()
-                path.append(item_name)
-                recursive_add(entry)
-                toc[tuple(path)] = None
-                path.pop()
-            else:
-                toc[tuple(path)] = item
-
-    recursive_add(repo_nav)
-    return toc

staging_docs/index.md

@@ -40,14 +40,14 @@ hide:
 
     Learn why important projects rely on Pulp to manage the lifecyle of huge *Software Content* collections.
 
-    [:octicons-arrow-right-24: Features](site:pulp-docs/docs/sections/help/more/why-pulp/)
+    [:octicons-arrow-right-24: Features](site:help/more/why-pulp/)
 
 -   :octicons-people-16:{ .lg .middle } **Get Involved**
 
     ---
 
     Join our communication channels and get to know the contributors and users of Pulp's strong ecosystem.
 
-    [:octicons-arrow-right-24: Community](site:pulp-docs/docs/sections/help/community/get-involved/)
+    [:octicons-arrow-right-24: Community](site:help/community/get-involved/)
 
 </div>