add mkdocs module

Author: mustafasoylu

src/somesy/mkdocs/__init__.py

@@ -0,0 +1,4 @@
+"""MkDocs module."""
+from .writer import MkDocs
+
+__all__ = ["MkDocs"]

src/somesy/mkdocs/models.py

@@ -0,0 +1,28 @@
+"""Pyproject models."""
+from typing import Optional
+
+from pydantic import (
+    BaseModel,
+    Field,
+)
+from typing_extensions import Annotated
+
+from somesy.core.types import HttpUrlStr
+
+
+class MkDocsConfig(BaseModel):
+    """MkDocs configuration model."""
+
+    model_config = dict(use_enum_values=True)
+
+    site_name: Annotated[
+        str,
+        Field(pattern=r"^[A-Za-z0-9]+([_-][A-Za-z0-9]+)*$", description="Site name"),
+    ]
+    site_description: Annotated[str, Field(description="Site description")] = None
+    site_author: Annotated[str, Field(description="Site authors")] = None
+    site_url: Annotated[Optional[HttpUrlStr], Field(description="Site homepage")] = None
+    repo_url: Annotated[
+        Optional[HttpUrlStr], Field(description="Package repository")
+    ] = None
+    repo_name: Annotated[str, Field(description="Repository name")] = None

src/somesy/mkdocs/writer.py

@@ -0,0 +1,98 @@
+"""Project documentation with Markdown (MkDocs) parser and saver."""
+import logging
+from pathlib import Path
+from typing import List, Optional
+
+from rich.pretty import pretty_repr
+from ruamel.yaml import YAML
+
+from somesy.core.models import Person, ProjectMetadata
+from somesy.core.writer import FieldKeyMapping, IgnoreKey, ProjectMetadataWriter
+from somesy.mkdocs.models import MkDocsConfig
+
+logger = logging.getLogger("somesy")
+
+
+class MkDocs(ProjectMetadataWriter):
+    """Project documentation with Markdown (MkDocs) parser and saver."""
+
+    def __init__(self, path: Path, create_if_not_exists: bool = False):
+        """Project documentation with Markdown (MkDocs) parser.
+
+        See [somesy.core.writer.ProjectMetadataWriter.__init__][].
+        """
+        self._yaml = YAML()
+        self._yaml.preserve_quotes = True
+
+        mappings: FieldKeyMapping = {
+            "name": ["site_name"],
+            "description": ["site_description"],
+            "homepage": ["site_url"],
+            "repository": ["repo_url"],
+            "authors": ["site_author"],
+            "documentation": IgnoreKey(),
+            "version": IgnoreKey(),
+            "maintainers": IgnoreKey(),
+            "license": IgnoreKey(),
+            "keywords": IgnoreKey(),
+        }
+        super().__init__(
+            path, create_if_not_exists=create_if_not_exists, direct_mappings=mappings
+        )
+
+    def _load(self):
+        """Load the MkDocs file."""
+        with open(self.path) as f:
+            self._data = self._yaml.load(f)
+
+    def _validate(self):
+        """Validate the MkDocs file."""
+        config = dict(self._get_property([]))
+        logger.debug(
+            f"Validating config using {MkDocsConfig.__name__}: {pretty_repr(config)}"
+        )
+        MkDocsConfig(**config)
+
+    def save(self, path: Optional[Path] = None) -> None:
+        """Save the MkDocs object to a file."""
+        path = path or self.path
+        self._yaml.dump(self._data, path)
+
+    @property
+    def authors(self):
+        """Return the only author from the source file as list."""
+        authors = []
+        try:
+            self._to_person(self._get_property(self._get_key("authors")))
+            authors = [self._get_property(self._get_key("authors"))]
+        except AttributeError:
+            logger.warning("Cannot convert authors to Person object.")
+        return authors
+
+    @authors.setter
+    def authors(self, authors: List[Person]) -> None:
+        """Set the authors of the project."""
+        authors = self._from_person(authors[0])
+        self._set_property(self._get_key("authors"), authors)
+
+    @staticmethod
+    def _from_person(person: Person):
+        """MkDocs Person is a string with full name."""
+        return person.to_name_email_string()
+
+    @staticmethod
+    def _to_person(person: str):
+        """MkDocs Person is a string with full name."""
+        return Person.from_name_email_string(person)
+
+    def sync(self, metadata: ProjectMetadata) -> None:
+        """Sync the MkDocs object with the ProjectMetadata object."""
+        self.name = metadata.name
+        self.description = metadata.description
+        # no author merge since it is a free text field
+        self.authors = metadata.authors()
+        if metadata.homepage:
+            self.homepage = str(metadata.homepage)
+        if metadata.repository:
+            self.repository = str(metadata.repository)
+            self.repo_name = metadata.repository.path