Skip to content

mkdocs

MkDocs module.

MkDocs

Bases: ProjectMetadataWriter

Project documentation with Markdown (MkDocs) parser and saver.

Source code in src/somesy/mkdocs/writer.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
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 = self._get_property(self._get_key("authors"))
        if authors is None or self._to_person(authors) is None:
            return []
        else:
            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) -> Optional[Person]:
        """MkDocs Person is a string with full name."""
        try:
            return Person.from_name_email_string(person)
        except (ValueError, AttributeError):
            logger.warning(f"Cannot convert {person} to Person object.")
            return None

    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

authors property writable 

authors

Return the only author from the source file as list.

__init__ 

__init__(path: Path, create_if_not_exists: bool = False)

Project documentation with Markdown (MkDocs) parser.

See somesy.core.writer.ProjectMetadataWriter.init.

Source code in src/somesy/mkdocs/writer.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
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
    )

save 

save(path: Optional[Path] = None) -> None

Save the MkDocs object to a file.

Source code in src/somesy/mkdocs/writer.py 
57
58
59
60
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)

sync 

sync(metadata: ProjectMetadata) -> None

Sync the MkDocs object with the ProjectMetadata object.

Source code in src/somesy/mkdocs/writer.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
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