make plugin.py more concise

Author: thomaszwagerman

README.md

@@ -126,7 +126,7 @@ part of the documentation build. This mean a physical file does not have to exis
 
 ## Contributing
 
-Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request on the [GitHub repository](#).
+Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request on the [GitHub repository](https://github.com/thomaszwagerman/mkdocs-authors-plugin).
 
 ## License
 

src/mkdocs_authors_plugin/plugin.py

@@ -3,7 +3,6 @@
 from mkdocs.plugins import BasePlugin, get_plugin_logger
 from mkdocs.config import config_options as c
 from mkdocs.structure.files import File
-from mkdocs.structure.pages import Page
 
 
 log = get_plugin_logger(__name__)
@@ -22,115 +21,103 @@ class AuthorsPlugin(BasePlugin):
 
     def on_pre_build(self, config):
         """
-        The 'on_pre_build' event is called once, before the documentation is built.
-        This is where we'll generate our authors page content.
+        Generates the authors page content from the YAML file before the build.
         """
         authors_file_path = os.path.join(
             config["docs_dir"], "..", self.config["authors_file"]
         )
-
         authors_data = []
         page_parameters = {}
 
-        if os.path.exists(authors_file_path):
-            with open(authors_file_path, "r", encoding="utf-8") as f:
-                try:
-                    raw_data = yaml.safe_load(f)
-
-                    if isinstance(raw_data, dict):
-                        if self.config["page_params_key"] in raw_data and isinstance(
-                            raw_data[self.config["page_params_key"]], dict
-                        ):
-                            page_parameters = raw_data[self.config["page_params_key"]]
-
-                        if "authors" in raw_data and isinstance(
-                            raw_data["authors"], dict
-                        ):
-                            for author_id, details in raw_data["authors"].items():
-                                details["id"] = author_id
-                                authors_data.append(details)
-                        else:
-                            log.warning(
-                                f"'{self.config['authors_file']}' does not contain an 'authors' key at the top level, or it's not a dictionary. No authors will be listed."
-                            )
-                            authors_data = []
-                    else:
-                        log.warning(
-                            f"'{self.config['authors_file']}' should contain a dictionary at the top level. No authors or page parameters will be loaded."
-                        )
-                        authors_data = []
-                        page_parameters = {}
-
-                except yaml.YAMLError as e:
-                    log.error(f"Error parsing '{self.config['authors_file']}': {e}")
-                    authors_data = []
-                    page_parameters = {}
-        else:
+        if not os.path.exists(authors_file_path):
             log.warning(
                 f"Authors file not found at '{authors_file_path}'. No authors page will be generated."
             )
             self.authors_markdown_content = "No authors file found. Please create a '.authors.yml' file in your project root."
             return
 
-        page_title = page_parameters.get("title", "Our Amazing Authors")
-        page_description = page_parameters.get("description")
+        try:
+            with open(authors_file_path, "r", encoding="utf-8") as f:
+                raw_data = yaml.safe_load(f)
+
+            if isinstance(raw_data, dict):
+                potential_page_params = raw_data.get(self.config["page_params_key"])
+                if isinstance(potential_page_params, dict):
+                    page_parameters = potential_page_params
+                else:
+                    log.warning(
+                        f"'{self.config['page_params_key']}' in '{self.config['authors_file']}' is not a dictionary. Page parameters will be ignored."
+                    )
+                    page_parameters = {}
+
+                authors_dict = raw_data.get("authors", {})
+
+                if isinstance(authors_dict, dict):
+                    authors_data = [
+                        {"id": aid, **details} for aid, details in authors_dict.items()
+                    ]
+                else:
+                    log.warning(
+                        f"'{self.config['authors_file']}' does not contain an 'authors' key as a dictionary. No authors will be listed."
+                    )
+            else:
+                log.warning(
+                    f"'{self.config['authors_file']}' should contain a dictionary at the top level. No authors or page parameters will be loaded."
+                )
+        except yaml.YAMLError as e:
+            log.error(f"Error parsing '{self.config['authors_file']}': {e}")
+        except Exception as e:
+            log.error(f"An unexpected error occurred while loading authors data: {e}")
 
-        # Get avatar styling from page_parameters, with defaults
+        self._generate_markdown_content(authors_data, page_parameters)
+        log.info(f"Authors page content generated for '{self.config['output_page']}'.")
+
+    def _generate_markdown_content(self, authors_data, page_parameters):
+        """Helper to generate the markdown string."""
+        page_title = page_parameters.get("title", "Our Amazing Authors")
+        page_description = page_parameters.get("description", "")
         avatar_size = page_parameters.get("avatar_size", 100)
         avatar_shape = page_parameters.get("avatar_shape", "square")
-        avatar_align = page_parameters.get(
-            "avatar_align", "center"
-        )  # Default to 'center'
+        avatar_align = page_parameters.get("avatar_align", "center")
 
-        markdown_content = f"# {page_title}\n\n"
+        markdown_parts = [f"# {page_title}\n\n"]
         if page_description:
-            markdown_content += f"{page_description}\n\n"
+            markdown_parts.append(f"{page_description}\n\n")
 
         if not authors_data:
-            markdown_content += "No authors found or an error occurred while loading the authors data.\n"
+            markdown_parts.append(
+                "No authors found or an error occurred while loading the authors data.\n"
+            )
         else:
             for author in authors_data:
-                markdown_content += f"## {author.get('name', 'Unknown Author')}\n"
-
-                avatar_html = ""  # Initialize avatar HTML for conditional placement
-                if author.get("avatar"):
-                    avatar_url = author["avatar"]
-                    author_name = author.get("name", "Avatar")
-
-                    style_attributes = f"width: {avatar_size}px; height: {avatar_size}px; object-fit: cover;"
-                    if avatar_shape == "circle":
-                        style_attributes += " border-radius: 50%;"
-                    else:  # Default or 'square'
-                        style_attributes += " border-radius: 0;"
-
-                    if avatar_align == "left":
-                        style_attributes += (
-                            " float: left; margin-right: 15px; margin-bottom: 10px;"
-                        )
-                        avatar_html = f'<img src="{avatar_url}" alt="{author_name} Avatar" style="{style_attributes}">'
-                    elif avatar_align == "right":
-                        style_attributes += (
-                            " float: right; margin-left: 15px; margin-bottom: 10px;"
+                markdown_parts.append(f"## {author.get('name', 'Unknown Author')}\n")
+
+                avatar_html = self._get_avatar_html(
+                    author, avatar_size, avatar_shape, avatar_align
+                )
+                if avatar_align not in [
+                    "left",
+                    "right",
+                ]:  # Center-aligned avatar needs to be handled as a block
+                    if avatar_html:
+                        markdown_parts.append(
+                            f'<p style="text-align: center;">{avatar_html}</p>\n'
                         )
-                        avatar_html = f'<img src="{avatar_url}" alt="{author_name} Avatar" style="{style_attributes}">'
-                    else:  # 'center' or default
-                        style_attributes += " display: block; margin: 0 auto 10px auto;"  # Add bottom margin for spacing
-                        # For center, wrap in a paragraph for block-level centering
-                        avatar_html = f'<p style="text-align: center;"><img src="{avatar_url}" alt="{author_name} Avatar" style="{style_attributes}"></p>'
+                    avatar_html = ""  # Clear for other alignments
 
-                # Insert avatar HTML
-                markdown_content += avatar_html
+                # Add avatar for left/right float and then other details
+                if avatar_html:
+                    markdown_parts.append(avatar_html)
 
-                # Now add the textual details that might wrap around a floated image
                 if author.get("affiliation"):
-                    markdown_content += f"**Affiliation:** {author['affiliation']}\n"
+                    markdown_parts.append(f"**Affiliation:** {author['affiliation']}\n")
 
                 if author.get("description"):
-                    markdown_content += f"\n {author['description']}\n"
+                    markdown_parts.append(f"\n{author['description']}\n")
 
                 if author.get("email"):
-                    markdown_content += (
-                        f"\n **Email:** [{author['email']}](mailto:{author['email']})\n"
+                    markdown_parts.append(
+                        f"\n**Email:** [{author['email']}](mailto:{author['email']})\n"
                     )
 
                 social_links = []
@@ -148,26 +135,44 @@ def on_pre_build(self, config):
                     )
 
                 if social_links:
-                    markdown_content += (
+                    markdown_parts.append(
                         "\n**Connect:** " + " | ".join(social_links) + "\n"
                     )
 
-                # Clear float after each author block if avatar was floated
                 if avatar_align in ["left", "right"]:
-                    markdown_content += '<div style="clear: both;"></div>\n'
+                    markdown_parts.append('<div style="clear: both;"></div>\n')
 
-                markdown_content += "\n---\n\n"
+                markdown_parts.append("\n---\n\n")
 
-        self.authors_markdown_content = markdown_content
-        log.info(f"Authors page content generated for '{self.config['output_page']}'.")
+        self.authors_markdown_content = "".join(markdown_parts)
+
+    def _get_avatar_html(self, author, size, shape, align):
+        """Generates the HTML for the author's avatar."""
+        if not author.get("avatar"):
+            return ""
+
+        avatar_url = author["avatar"]
+        author_name = author.get("name", "Avatar")
+
+        style_attributes = f"width: {size}px; height: {size}px; object-fit: cover;"
+        style_attributes += (
+            " border-radius: 50%;" if shape == "circle" else " border-radius: 0;"
+        )
+
+        if align == "left":
+            style_attributes += " float: left; margin-right: 15px; margin-bottom: 10px;"
+        elif align == "right":
+            style_attributes += " float: right; margin-left: 15px; margin-bottom: 10px;"
+        elif align == "center":
+            style_attributes += " display: block; margin: 0 auto 10px auto;"
+
+        return f'<img src="{avatar_url}" alt="{author_name} Avatar" style="{style_attributes}">'
 
     def on_files(self, files, config):
         """
-        The 'on_files' event is called after the files are gathered.
-        We need to ensure our generated authors.md file is included in the build.
+        Ensures the generated authors.md file is included in the MkDocs build.
         """
         output_page_name = self.config["output_page"]
-
         if not any(f.src_path == output_page_name for f in files):
             generated_file = File(
                 path=output_page_name,
@@ -181,8 +186,7 @@ def on_files(self, files, config):
 
     def on_page_read_source(self, page, config):
         """
-        The 'on_page_read_source' event is called when MkDocs reads the source
-        for a page. We'll intercept our generated page and provide its content.
+        Intercepts the generated page and provides its content.
         """
         output_page_name = self.config["output_page"]
         if page.file.src_path == output_page_name: