Fix section ordering and opt-out openapi from serve

src/pulp_docs/cli.py

@@ -6,7 +6,7 @@
 import git
 from mkdocs.__main__ import cli as mkdocs_cli
 
-from pulp_docs.context import ctx_blog, ctx_docstrings, ctx_draft, ctx_dryrun, ctx_path
+from pulp_docs.context import ctx_blog, ctx_docstrings, ctx_draft, ctx_dryrun, ctx_openapi, ctx_path
 from pulp_docs.plugin import ComponentLoader, ComponentSpec, default_lookup_paths
 
 
@@ -94,6 +94,20 @@ async def clone_repository(repo_url: str) -> None:
 )
 
 
+def openapi_callback(ctx: click.Context, param: click.Parameter, value: bool) -> bool:
+    ctx_openapi.set(value)
+    return value
+
+
+openapi_option = click.option(
+    "--openapi/--no-openapi",
+    expose_value=False,
+    default=False,
+    callback=openapi_callback,
+    help="Generate OpenAPI specs.",
+)
+
+
 def fetch_repositories(
     dest: Path,
     config_file: Path | None = None,
@@ -211,3 +225,5 @@ def get_default_mkdocs() -> Path | None:
     config_file_opt = next(filter(lambda opt: opt.name == "config_file", serve_options))
     config_file_opt.envvar = "PULPDOCS_DIR"
     config_file_opt.default = get_default_mkdocs()
+
+openapi_option(main.commands.get("serve"))

src/pulp_docs/context.py

@@ -5,3 +5,4 @@
 ctx_draft = ContextVar("ctx_draft", default=False)
 ctx_path = ContextVar("ctx_path", default=None)
 ctx_dryrun = ContextVar("ctx_dryrun", default=False)
+ctx_openapi = ContextVar("ctx_openapi", default=True)

src/pulp_docs/plugin.py

@@ -19,7 +19,7 @@
 from mkdocs.structure.pages import Page
 from mkdocs.utils.templates import TemplateContext
 
-from pulp_docs.context import ctx_blog, ctx_docstrings, ctx_draft, ctx_dryrun, ctx_path
+from pulp_docs.context import ctx_blog, ctx_docstrings, ctx_draft, ctx_dryrun, ctx_openapi, ctx_path
 from pulp_docs.openapi import OpenAPIGenerator, OpenApiPlugin, PulpResolutionError
 
 log = get_plugin_logger(__name__)
@@ -183,7 +183,7 @@ def load_all(self, generate_openapi: bool = False) -> LoadResult:
 
         return LoadResult(
             all_specs=self.component_specs,
-            loaded=sorted(loaded_comps, key=lambda c: c.component_name),
+            loaded=loaded_comps,
             missing=sorted(missing_comps, key=lambda c: c.component_name),
         )
 
@@ -479,7 +479,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
         # Load components
         lookup_paths = ctx_path.get() or default_lookup_paths()
         component_loader = ComponentLoader.from_plugin(self, lookup_paths)
-        load_result = component_loader.load_all(generate_openapi=True)
+        load_result = component_loader.load_all(generate_openapi=ctx_openapi.get())
         if load_result.missing and not self.draft:
             missing_names = sorted([p.component_name for p in load_result.missing])
             raise PluginError(