Section-level re-structures (#19)

* Remove (global) Reference section in favor of persona-scoped reference sections
* Improve sections overviews
* add quicklinks table
* Improve help page

Author: pedro-psb

Diff for: 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,24 @@ 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
+    changes_dir = Path(docs_dir / "changes")
+    changes_dir.mkdir(exist_ok=True)
+    for changelog_name in ("CHANGELOG.md", "CHANGES.md", "CHANGES.rst"):
+        changelog_path = Path(src_dir / changelog_name)
+        if changelog_path.exists():
+            shutil.copy(changelog_path, changes_dir / "changelog.md")
+            repo.status.has_changelog = True
+            return
+
+    # Create placeholder, case it was not possible to fetch one
+    empty_changelog = changes_dir / "changelog.md"
+    empty_changelog.write_text(
+        "# Changelog\n\nThe repository does not provide a changelog or there was a problem fetching it."
+    )
 
 
 def _generate_rest_api_page(docs_dir: Path, repo_name: str, repo_title: str):
@@ -243,8 +252,29 @@ 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"
+        _repo_type = [repo_type] if repo_type else None
+        repos_list = sorted(
+            repos.get_repos(repo_types=_repo_type), key=lambda x: x.title
+        )
+        repos_data = [
+            {
+                "title": repo.title,
+                "version": "3.12.1",
+                "rest_api_url": f"https://docs.pulpproject.org/{repo.name}/restapi.html",
+                "codebase_url": f"https://github.com/{repo.owner}/{repo.name}",
+                "changelog_url": f"site:{repo.name}/changes/changelog/",
+            }
+            for repo in repos_list
+        ]
+        return repos_data
+
 
 def on_pre_page_macros(env):
     """The mkdocs-macros hook just before an inidvidual page render."""

Diff for: src/pulp_docs/navigation.py

@@ -56,16 +56,8 @@ def grouped_by_persona(tmpdir: Path, repos: Repos):
                     {content-type}
     """
     f = AgregationUtils(tmpdir, repos)
-    help_section = [
-        {"Overview": f.section_file("help/index.md")},
-        {
-            "Bugs, Feature and Backport Requests": f.section_file(
-                "help/bugs-features.md"
-            )
-        },
-    ]
     usage_section = [
-        {"Overview": f.section_file("usage/index.md")},
+        {"Overview": f.section_file("user/index.md")},
         {
             "Pulpcore": [
                 f.section(
@@ -113,7 +105,7 @@ def grouped_by_persona(tmpdir: Path, repos: Repos):
         ),
     ]
     development_section = [
-        {"Overview": f.section_file("development/index.md")},
+        {"Overview": f.section_file("dev/index.md")},
         {
             "Pulpcore": [
                 f.section(
@@ -126,26 +118,38 @@ 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"])},
     ]
-    reference_section = [
-        {"Overview": f.section_file("reference/index.md")},
-        {"Repository Map": f.section_file("reference/01-repository-map.md")},
-        {"Glossary": f.section_file("reference/02-glossary.md")},
-        {"Repositories": f.repo_reference_grouping()},
+    help_section = [
+        *f.get_children("pulp-docs/docs/sections/help/community"),
+        {"Documentation Usage": f.get_children("pulp-docs/docs/sections/help/using-this-doc")},
+        {
+            "Changelogs": [
+                {"Pulpcore": "pulpcore/changes/changelog.md"},
+                {
+                    "Plugins": sorted(
+                        f.repo_grouping(
+                            "{repo}/changes", repo_types=["content"]
+                        ).items()
+                    )
+                },
+                {
+                    "Extra": sorted(
+                        f.repo_grouping("{repo}/changes", repo_types=["other"]).items()
+                    )
+                },
+            ]
+        },
+        {"Governance": f.get_children("pulp-docs/docs/sections/help/governance")},
     ]
 
     # Main Section
     navigation = [
         {"Home": "index.md"},
         {"User Manual": usage_section},
         {"Admin Manual": admin_section},
-        {"Development": development_section},
-        {"Reference": reference_section},
+        {"Developer Manual": development_section},
         {"Help": help_section},
     ]
     return navigation

Diff for: src/pulp_docs/repository.py

@@ -203,6 +203,10 @@ class SubPackage:
     local_basepath = None
     branch_in_use = ""
     branch = ""
+    owner = ""
+
+    def __post_init__(self):
+        self.owner = self.subpackage_of
 
 
 @dataclass

Diff for: 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
@@ -67,7 +68,7 @@ def repo_grouping(
 
         Arguments:
             template_str: The template with fields to expand. Accepts combination of '{repo}' and '{content}'
-            repos: The set of repos to use. Accepts list with combination of "core", "content" and "other"
+            repo_types: The set of repos to use. Accepts list with combination of "core", "content" and "other"
             content_types: The set of content-types to use. Accepts combination of "guides", "learn" and "tutorial"
 
         Example:
@@ -93,7 +94,7 @@ def repo_grouping(
 
         # Selected  a set of repos
         selected_repos = []
-        selected_content = content_types or ["tutorials", "guides", "learn"]
+        selected_content = content_types or ["tutorials", "guides", "learn", "reference"]
         if not repo_types:  # default case
             selected_repos = self.repos.all
         else:
@@ -107,7 +108,7 @@ def repo_grouping(
                 )
                 _repo_content = self.get_children(lookup_path)
                 if _repo_content:
-                    _nav[repo.title] = _repo_content
+                    _nav[repo.title] = _repo_content if len(_repo_content) > 1 else _repo_content[0]
         # Expand content-types
         else:
             for repo in selected_repos:
@@ -177,7 +178,7 @@ def repo_reference_grouping(self):
 
     def section_file(self, section_and_filename: str):
         """Get a markdown file from the website section folder."""
-        basepath = "pulpcore/docs/sections"
+        basepath = "pulp-docs/docs/sections"
         return f"{basepath}/{section_and_filename}"
 
     def section_children(self, section_name: str):

Diff for: staging_docs/dev/reference/markdown-cheatsheet.md

@@ -0,0 +1,153 @@
+# Markdown Cheatsheet
+
+There are basic markdown features recommended for use in Pulp.
+
+### Internal links
+
+=== "Template"
+
+    ```markdown
+    [My Link](site:{repo-name}/docs/{persona}/{content-type}/some-page.md).
+    ```
+
+=== "Sample"
+
+    ```markdown
+    [My Link](site:pulp-docs/docs/dev/reference/markdown-cheatsheet.md).
+    ```
+
+=== "Sample Rendered"
+
+    ```markdown
+    [My Link](http://127.0.0.1:8000/pulp-docs/docs/dev/reference/markdown-cheatsheet/).
+    ```
+
+- This is enabled by [mkdocs-site-urls](https://github.com/octoprint/mkdocs-site-urls) plugin.
+- This is preferred over *relative* links because of our complex structure. See tradeoffs [here](https://github.com/pedro-psb/pulp-docs/issues/2)
+
+
+### Codeblocks
+
+
+=== "Raw"
+
+    ````
+    ```
+    <location "/pulp/api/v3/foo_route">
+    proxypass /pulp/api http://${pulp-api}/pulp/api
+    proxypassreverse /pulp/api http://${pulp-api}/pulp/api
+    requestheader set foo "asdf"
+    </location>
+    ```
+    ````
+
+    ---
+
+    ```
+    <location "/pulp/api/v3/foo_route">
+    proxypass /pulp/api http://${pulp-api}/pulp/api
+    proxypassreverse /pulp/api http://${pulp-api}/pulp/api
+    requestheader set foo "asdf"
+    </location>
+    ```
+
+=== "Python Language"
+
+    ````
+    ```python
+    serializer = mymodelserializer(data=data)
+    serializer.is_valid(raise_exception=true)
+    instance = serializer.create(serializer.validated_data)
+    ```
+    ````
+
+    ---
+
+    ```python
+    serializer = mymodelserializer(data=data)
+    serializer.is_valid(raise_exception=true)
+    instance = serializer.create(serializer.validated_data)
+    ```
+
+=== "Python REPL"
+
+    ````
+    ```python
+    >>> serializer = mymodelserializer(data=data)
+    >>> serializer.is_valid(raise_exception=true)
+    >>> instance = serializer.create(serializer.validated_data)
+    Some output
+    ```
+    ````
+
+    ---
+
+    ```python
+    >>> serializer = mymodelserializer(data=data)
+    >>> serializer.is_valid(raise_exception=true)
+    >>> instance = serializer.create(serializer.validated_data)
+    Some output
+    ```
+
+=== "With 'Title'"
+
+    ````
+    ```bash title="script.sh"
+    pulp file repository update --name myrepo --retained-versions 1
+    ```
+    ````
+
+    ---
+
+    ```bash title="script.sh"
+    pulp file repository update --name myrepo --retained-versions 1
+    ```
+
+### Tabbed content
+
+
+<div class="grid" markdown>
+
+````
+=== "Run"
+
+    ```bash
+    cat myfile.txt
+    ```
+
+=== "Output"
+
+    ```bash
+    line1
+    line2
+    line3
+    ```
+````
+
+=== "Run"
+
+    ```bash
+    cat myfile.txt
+    ```
+
+=== "Output"
+
+    ```bash
+    line1
+    line2
+    line3
+    ```
+
+</div>
+
+- [See mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#usage)
+- Each tab title must be in quotes
+- Each tab block must have 4 spaces of indent
+- Put space around `=== "Title"`
+
+### Admonitions
+
+[See mkdocs-material](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types)
+
+Use them wisely.
+

Diff for: 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>