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 
16
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
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

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 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
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 
56
57
58
59
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 
88
89
90
91
92
93
94
95
96
97
98
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