|
| 1 | +from __future__ import annotations |
| 2 | + |
| 3 | +from pathlib import Path |
| 4 | +from typing import TYPE_CHECKING |
| 5 | + |
| 6 | +from usethis._config_file import MkDocsYMLManager |
| 7 | +from usethis._console import box_print |
| 8 | +from usethis._integrations.project.name import get_project_name |
| 9 | +from usethis._integrations.uv.deps import Dependency |
| 10 | +from usethis._integrations.uv.used import is_uv_used |
| 11 | +from usethis._tool.base import Tool |
| 12 | +from usethis._tool.config import ConfigEntry, ConfigItem, ConfigSpec |
| 13 | + |
| 14 | +if TYPE_CHECKING: |
| 15 | + from usethis._io import KeyValueFileManager |
| 16 | + |
| 17 | + |
| 18 | +class MkDocsTool(Tool): |
| 19 | + # https://www.mkdocs.org/ |
| 20 | + |
| 21 | + @property |
| 22 | + def name(self) -> str: |
| 23 | + return "MkDocs" |
| 24 | + |
| 25 | + def print_how_to_use(self) -> None: |
| 26 | + if is_uv_used(): |
| 27 | + box_print("Run 'uv run mkdocs build' to build the documentation.") |
| 28 | + box_print("Run 'uv run mkdocs serve' to serve the documentation locally.") |
| 29 | + else: |
| 30 | + box_print("Run 'mkdocs build' to build the documentation.") |
| 31 | + box_print("Run 'mkdocs serve' to serve the documentation locally.") |
| 32 | + |
| 33 | + def get_doc_deps(self, *, unconditional: bool = False) -> list[Dependency]: |
| 34 | + deps = [Dependency(name="mkdocs")] |
| 35 | + |
| 36 | + if unconditional: |
| 37 | + deps.append(Dependency(name="mkdocs-material")) |
| 38 | + |
| 39 | + return deps |
| 40 | + |
| 41 | + def get_config_spec(self) -> ConfigSpec: |
| 42 | + """Get the configuration specification for this tool. |
| 43 | +
|
| 44 | + This includes the file managers and resolution methodology. |
| 45 | + """ |
| 46 | + return ConfigSpec.from_flat( |
| 47 | + file_managers=[ |
| 48 | + MkDocsYMLManager(), |
| 49 | + ], |
| 50 | + resolution="first_content", |
| 51 | + config_items=[ |
| 52 | + ConfigItem( |
| 53 | + description="Site Name", |
| 54 | + root={ |
| 55 | + Path("mkdocs.yml"): ConfigEntry( |
| 56 | + keys=["site_name"], |
| 57 | + get_value=lambda: get_project_name(), |
| 58 | + ), |
| 59 | + }, |
| 60 | + ), |
| 61 | + ConfigItem( |
| 62 | + description="Navigation", |
| 63 | + root={ |
| 64 | + Path("mkdocs.yml"): ConfigEntry( |
| 65 | + keys=["nav"], |
| 66 | + get_value=lambda: [{"Home": "index.md"}], |
| 67 | + ), |
| 68 | + }, |
| 69 | + ), |
| 70 | + ], |
| 71 | + ) |
| 72 | + |
| 73 | + def get_managed_files(self) -> list[Path]: |
| 74 | + """Get (relative) paths to files managed by (solely) this tool.""" |
| 75 | + return [Path("mkdocs.yml")] |
| 76 | + |
| 77 | + def preferred_file_manager(self) -> KeyValueFileManager: |
| 78 | + """If there is no currently active config file, this is the preferred one.""" |
| 79 | + # Should set the mkdocs.yml file manager as the preferred one |
| 80 | + return MkDocsYMLManager() |
0 commit comments