Refactor names and structure

- /utils for non essential things
- extract navigation.py module. It needs some special care later
- module renames:
  - plugin_repos -> repository
  - main -> cli

README.md

@@ -15,7 +15,7 @@ This packages is:
 - A `mkdocs-macros-plugin` [pluget](https://mkdocs-macros-plugin.readthedocs.io/en/latest/pluglets/). [relevant-code]()
 - A repository for common doc website asset. [relevant-code](https://github.com/pedro-psb/pulp-docs/tree/main/src/pulp_docs/docs)
 - A centralized entrypoint for installing doc-related packages/tooling. (via its own requirements)
-- A CLI for doc-related tasks, like serving and building. [relevant-code](https://github.com/pedro-psb/pulp-docs/blob/main/src/pulp_docs/main.py)
+- A CLI for doc-related tasks, like serving and building. [relevant-code](https://github.com/pedro-psb/pulp-docs/blob/main/src/pulp_docs/cli.py)
 
 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.

pyproject.toml

@@ -15,7 +15,7 @@ dependencies = [
 ]
 
 [project.scripts]
-pulp-docs = "pulp_docs.main:main"
+pulp-docs = "pulp_docs.cli:main"
 
 [tool.setuptools]
 include-package-data=true

src/pulp_docs/mkdocs_macros.py

@@ -21,10 +21,12 @@
 import typing as t
 from pathlib import Path
 
+import rich
 from importlib_resources import as_file, files
 
-from pulp_docs.main import Config
-from pulp_docs.plugin_repos import Repos
+from pulp_docs.cli import Config
+from pulp_docs.navigation import get_navigation
+from pulp_docs.repository import Repos
 
 # the name of the docs in the source repositories
 SRC_DOCS_DIRNAME = "staging_docs"
@@ -176,8 +178,6 @@ def print_user_repo(repos: Repos, config: Config):
             "[pulp-docs] No local checkouts found. Serving in read-only mode."
         )
 
-    import rich
-
     if config.verbose:
         report = {
             "config": config.get_environ_dict(),
@@ -199,102 +199,6 @@ def print_user_repo(repos: Repos, config: Config):
     print("*" * 79)
 
 
-def get_navigation(tmpdir: Path, repos: Repos):
-    """The dynamic generated 'nav' section of mkdocs.yml"""
-
-    # {repo}/docs/{persona}/{content-type}/*md
-    # {repo}/docs/reference/*md
-    def get_children(path: t.Union[str, Path]):
-        _path = tmpdir / path if isinstance(path, str) else path
-        result = [
-            str(file.relative_to(tmpdir))
-            for file in _path.glob("*.md")
-            if not file.name.startswith("_")
-        ]
-        return result
-
-    def expand_repos(template_str: str):
-        _nav = {}
-        for repo in repos.content:
-            lookup_path = tmpdir / template_str.format(repo=repo.name)
-            _repo_content = get_children(lookup_path)
-            _nav[repo.title] = _repo_content
-        return _nav
-
-    def expand_reference(template_str: str):
-        _nav = {}
-        for repo in repos.all:
-            lookup_path = tmpdir / template_str.format(repo=repo.name)
-            _repo_content = get_children(lookup_path)
-            reference_section = [
-                {"REST API": f"{repo.name}/docs/rest_api.md"},
-                {"Readme": f"{repo.name}/README.md"},
-                {"Code API": _repo_content},
-                {"Changelog": f"{repo.name}/CHANGELOG.md"},
-            ]
-            _nav[repo.title] = reference_section
-        return _nav
-
-    def from_core(url: str):
-        corename = "pulpcore"
-        return f"{corename}/{url}"
-
-    getting_started = [
-        {"Overview": from_core("docs/sections/getting_started/index.md")},
-        {
-            "Quickstart": get_children(
-                from_core("docs/sections/getting_started/quickstart")
-            )
-        },
-        {
-            "Fundamentals": get_children(
-                from_core("docs/sections/getting_started/fundamentals")
-            )
-        },
-    ]
-    guides = [
-        {"Overview": from_core("docs/sections/guides/index.md")},
-        {"For Content-Management": expand_repos("{repo}/docs/content-manager/guides")},
-        {"For Sys-Admins": expand_repos("{repo}/docs/sys-admin/guides")},
-    ]
-    learn = [
-        {"Overview": from_core("docs/sections/learn/index.md")},
-        {"For Content-Management": expand_repos("{repo}/docs/content-manager/learn")},
-        {"For Sys-Admins": expand_repos("{repo}/docs/sys-admin/learn")},
-    ]
-    reference = [
-        {"Overview": from_core("docs/sections/reference/index.md")},
-        {"Repository Map": from_core("docs/sections/reference/01-repository-map.md")},
-        {"Glossary": from_core("docs/sections/reference/02-glossary.md")},
-        {"Repositories": expand_reference("{repo}/docs/reference")},
-    ]
-    development = [
-        {"Overview": from_core("docs/sections/development/index.md")},
-        {
-            "Quickstart": get_children(
-                from_core("docs/sections/development/quickstart/")
-            )
-        },
-        {
-            "Onboarding": get_children(
-                from_core("docs/sections/development/onboarding/")
-            )
-        },
-        {"Guides": get_children("core/docs/sections/development/guides/")},
-    ]
-
-    # main navigation
-    navigation = [
-        {"Home": "index.md"},
-        {"Getting Started": getting_started},
-        {"Guides": guides},
-        {"Learn": learn},
-        {"Reference": reference},
-        {"Development": development},
-    ]
-    return navigation
-
-
 def define_env(env):
     """The mkdocs-marcros 'on_configuration' hook. Used to setup the project."""
     # Load configuration from environment
@@ -333,5 +237,6 @@ def define_env(env):
 
 
 def on_post_build(env):
+    """The mkdocs-marcros 'on_post_build' hook. Used to print summary report for end user."""
     # Log relevant most useful information for end-user
     print_user_repo(repos=env.conf["pulp_repos"], config=env.conf["pulp_config"])

src/pulp_docs/navigation.py

@@ -0,0 +1,100 @@
+import typing as t
+from pathlib import Path
+
+from pulp_docs.repository import Repos
+
+
+def get_navigation(tmpdir: Path, repos: Repos):
+    """The dynamic generated 'nav' section of mkdocs.yml"""
+
+    # {repo}/docs/{persona}/{content-type}/*md
+    # {repo}/docs/reference/*md
+    def get_children(path: t.Union[str, Path]):
+        _path = tmpdir / path if isinstance(path, str) else path
+        result = [
+            str(file.relative_to(tmpdir))
+            for file in _path.glob("*.md")
+            if not file.name.startswith("_")
+        ]
+        return result
+
+    def expand_repos(template_str: str):
+        _nav = {}
+        for repo in repos.content:
+            lookup_path = tmpdir / template_str.format(repo=repo.name)
+            _repo_content = get_children(lookup_path)
+            _nav[repo.title] = _repo_content
+        return _nav
+
+    def expand_reference(template_str: str):
+        _nav = {}
+        for repo in repos.all:
+            lookup_path = tmpdir / template_str.format(repo=repo.name)
+            _repo_content = get_children(lookup_path)
+            reference_section = [
+                {"REST API": f"{repo.name}/docs/rest_api.md"},
+                {"Readme": f"{repo.name}/README.md"},
+                {"Code API": _repo_content},
+                {"Changelog": f"{repo.name}/CHANGELOG.md"},
+            ]
+            _nav[repo.title] = reference_section
+        return _nav
+
+    def from_core(url: str):
+        corename = "pulpcore"
+        return f"{corename}/{url}"
+
+    getting_started = [
+        {"Overview": from_core("docs/sections/getting_started/index.md")},
+        {
+            "Quickstart": get_children(
+                from_core("docs/sections/getting_started/quickstart")
+            )
+        },
+        {
+            "Fundamentals": get_children(
+                from_core("docs/sections/getting_started/fundamentals")
+            )
+        },
+    ]
+    guides = [
+        {"Overview": from_core("docs/sections/guides/index.md")},
+        {"For Content-Management": expand_repos("{repo}/docs/content-manager/guides")},
+        {"For Sys-Admins": expand_repos("{repo}/docs/sys-admin/guides")},
+    ]
+    learn = [
+        {"Overview": from_core("docs/sections/learn/index.md")},
+        {"For Content-Management": expand_repos("{repo}/docs/content-manager/learn")},
+        {"For Sys-Admins": expand_repos("{repo}/docs/sys-admin/learn")},
+    ]
+    reference = [
+        {"Overview": from_core("docs/sections/reference/index.md")},
+        {"Repository Map": from_core("docs/sections/reference/01-repository-map.md")},
+        {"Glossary": from_core("docs/sections/reference/02-glossary.md")},
+        {"Repositories": expand_reference("{repo}/docs/reference")},
+    ]
+    development = [
+        {"Overview": from_core("docs/sections/development/index.md")},
+        {
+            "Quickstart": get_children(
+                from_core("docs/sections/development/quickstart/")
+            )
+        },
+        {
+            "Onboarding": get_children(
+                from_core("docs/sections/development/onboarding/")
+            )
+        },
+        {"Guides": get_children("core/docs/sections/development/guides/")},
+    ]
+
+    # main navigation
+    navigation = [
+        {"Home": "index.md"},
+        {"Getting Started": getting_started},
+        {"Guides": guides},
+        {"Learn": learn},
+        {"Reference": reference},
+        {"Development": development},
+    ]
+    return navigation