Merge pull request #70 from daizutabi/feature-template

Update stylesheets

README.md

@@ -5,7 +5,7 @@
 [![Coverage Status][codecov-image]][codecov-link]
 [![Python Version][python-v-image]][python-v-link]
 
-MkAPI is a plugin for [MkDocs](https://www.mkdocs.org/) to generate a
+MkAPI is a plugin for [MkDocs](https://www.mkdocs.org/) to generate
 API documentation for your Python project.
 
 MkAPI supports two styles of docstrings:

docs/index.md

@@ -2,7 +2,7 @@
 
 [![Built with Material for MkDocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?style=for-the-badge&logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
 
-MkAPI is a plugin for [MkDocs](https://www.mkdocs.org/) to generate a
+MkAPI is a plugin for [MkDocs](https://www.mkdocs.org/) to generate
 API documentation for your Python project.
 
 MkAPI supports two styles of docstrings:

docs/usage/object.md

@@ -31,7 +31,7 @@ examples/
 ```
 
 <style type="text/css">
-.mkapi-container {
+.mkapi-content {
   border: dashed #22772288;
 }
 </style>

mkdocs.yml

@@ -17,13 +17,13 @@ theme:
       primary: indigo
       accent: indigo
       toggle:
-        icon: material/toggle-switch
+        icon: material/weather-sunny
         name: Switch to dark mode
     - scheme: slate
       primary: black
       accent: black
       toggle:
-        icon: material/toggle-switch-off-outline
+        icon: material/weather-night
         name: Switch to light mode
   features:
     - content.tooltips
@@ -34,6 +34,7 @@ theme:
     - navigation.sections
     - navigation.tabs
     - navigation.tabs.sticky
+    - navigation.top
     - navigation.tracking
 plugins:
   - search:
@@ -56,10 +57,13 @@ nav:
     - usage/object.md
     - usage/page.md
     - usage/config.md
-  # - API: <api>/mkapi.***
+  - API: <api>/mkapi.***
   - Examples: <api>/examples.**
   - Schemdraw: <api>/schemdraw.***
   - Polars: <api>/polars.***
   - Altair: <api>/altair.***
 extra_css:
-  - stylesheets/extra.css
+  - stylesheets/extra.css
+watch:
+  - src/mkapi/stylesheets
+  - src/mkapi/templates

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mkapi"
-description = "A documentation generation tool for MkDocs"
+description = "A plugin for MkDocs to generate API documentation"
 readme = "README.md"
 license = "MIT"
 authors = [{ name = "daizutabi", email = "[email protected]" }]

src/mkapi/plugins.py

@@ -15,7 +15,6 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, ClassVar
 
-import yaml
 from halo import Halo
 from mkdocs.config import Config, config_options
 from mkdocs.plugins import BasePlugin, get_plugin_logger
@@ -79,7 +78,7 @@ def on_files(self, files: Files, config: MkDocsConfig, **kwargs) -> Files:
         for file in files:
             if file.src_uri.startswith(f"{self.config.src_dir}/"):
                 file.inclusion = InclusionLevel.NOT_IN_NAV
-        for file in _collect_theme_files(config, self):
+        for file in _collect_stylesheets(config, self):
             files.append(file)
         return files
 
@@ -132,13 +131,6 @@ def _update_bar(self, uri: str) -> None:
     def on_post_build(self, *, config: MkDocsConfig) -> None:
         self.bar.close()
 
-    def on_serve(self, server, config: MkDocsConfig, builder, **kwargs):
-        if self.config.debug:
-            for path in ["themes", "templates"]:
-                path_str = (Path(mkapi.__file__).parent / path).as_posix()
-                server.watch(path_str, builder)
-        return server
-
     def on_shutdown(self) -> None:
         for path in MkAPIPlugin.api_dirs:
             if path.exists():
@@ -252,35 +244,24 @@ def predicate(name: str) -> bool:
         spinner.stop()
 
 
-def _collect_theme_files(config: MkDocsConfig, plugin: MkAPIPlugin) -> list[File]:  # noqa: ARG001
-    root = Path(mkapi.__file__).parent / "themes"
+def _collect_stylesheets(config: MkDocsConfig, plugin: MkAPIPlugin) -> list[File]:  # noqa: ARG001
+    root = Path(mkapi.__file__).parent / "stylesheets"
     docs_dir = config.docs_dir
     config.docs_dir = root.as_posix()
-    theme_files = get_files(config)
+    stylesheet_files = get_files(config)
     config.docs_dir = docs_dir
     theme_name = config.theme.name or "mkdocs"
     files: list[File] = []
     css: list[str] = []
-    js: list[str] = []
-    for file in theme_files:
+    for file in stylesheet_files:
         path = Path(file.src_path).as_posix()
-        if path.endswith(".css"):
-            if "common" in path or theme_name in path:
-                files.append(file)
-                css.append(path)
-        elif path.endswith(".js"):
+        if path.endswith("mkapi-common.css"):
+            files.insert(0, file)
+            css.insert(0, path)
+        elif path.endswith(f"mkapi-{theme_name}.css"):
             files.append(file)
-            js.append(path)
-        elif path.endswith((".yml", ".yaml")):
-            with (root / path).open() as f:
-                data = yaml.safe_load(f)
-            if isinstance(data, dict):
-                css.extend(data.get("extra_css", []))
-                js.extend(data.get("extra_javascript", []))
-    css = [f for f in css if f not in config.extra_css]
-    js = [f for f in js if f not in config.extra_javascript]
-    config.extra_css.extend(css)
-    config.extra_javascript.extend(js)
+            css.append(path)
+    config.extra_css = [*css, *config.extra_css]
     return files
 
 
@@ -290,7 +271,6 @@ def _replace_toc(
     depth: int = 0,
 ) -> None:
     for link in toc:
-        # link.id = link.id.replace("\0295\03", "_")
         link.title = re.sub(r"\s+\[.+?\]", "", link.title)  # Remove source link.
         if title:
             link.title = title(link.title, depth)

src/mkapi/stylesheets/mkapi-common.css

@@ -0,0 +1,106 @@
+h1.mkapi-heading,
+h2.mkapi-heading,
+h3.mkapi-heading,
+h4.mkapi-heading,
+h5.mkapi-heading,
+p.mkapi-heading {
+  font-size: 85%;
+  font-weight: normal;
+  text-align-last: justify;
+  margin-bottom: 0px;
+}
+.mkapi-heading-name {
+  color: var(--mkapi-heading-name-color);
+}
+.mkapi-heading-name a {
+  color: unset;
+}
+p.mkapi-object {
+  margin-block-start: 0px;
+  margin-block-end: 0px;
+  border-top: 2px solid var(--mkapi-object-border-color);
+}
+.mkapi-object-kind {
+  color: var(--mkapi-object-kind-color);
+  font-size: 90%;
+  font-style: italic;
+}
+.mkapi-object-name {
+  color: var(--mkapi-object-name-color);
+  font-family: var(--mkapi-object-name-font-family);
+  font-weight: bold;
+  font-size: 1.1em;
+}
+.mkapi-prefix {
+  color: var(--mkapi-prefix-color);
+}
+.mkapi-dot {
+  color: var(--mkapi-punctuation-color);
+}
+.mkapi-arg {
+  color: var(--mkapi-arg-color);
+  font-style: italic;
+}
+.mkapi-default, .mkapi-star {
+  color: var(--mkapi-variable-color);
+}
+.mkapi-paren {
+  color: var(--mkapi-punctuation-color);
+  margin-left: 2px;
+  margin-right: 2px;
+}
+.mkapi-star, .mkapi-slash {
+  color: var(--mkapi-punctuation-color);
+  margin-left: 0px;
+  margin-right: 2px;
+}
+.mkapi-comma, .mkapi-colon {
+  color: var(--mkapi-punctuation-color);
+  margin-left: 2px;
+  margin-right: 0px;
+}
+.mkapi-equal, .mkapi-arrow {
+  color: var(--mkapi-punctuation-color);
+  margin-left: 0px;
+  margin-right: 0px;
+}
+p.mkapi-object-bases {
+  color: var(--mkapi-object-bases-color);
+  font-size: 85%;
+  margin-block-start: 0px;
+}
+.mkapi-section-name {
+  color: var(--mkapi-section-name-color);
+  border-bottom: thin solid var(--mkapi-section-border-color);
+  font-size: 1.05em;
+}
+.mkapi-item-name {
+  color: var(--mkapi-item-name-color);
+  font-weight: bold;
+}
+.mkapi-item-type, .mkapi-object-type, .mkapi-ann, .mkapi-return {
+  color: var(--mkapi-type-color);
+}
+.mkapi-example-input pre {
+  margin-bottom: 0px;
+}
+.mkapi-example-output pre {
+  margin-top: 0px;
+}
+.mkapi-example-input code {
+  font-size: 85%;
+  background-color: var(--mkapi-example-bg-color);
+}
+.mkapi-example-output code {
+  font-size: 85%;
+  border: solid var(--mkapi-example-bg-color);
+  background-color: transparent;
+}
+.mkapi-source code {
+  font-size: 85%;
+}
+.mkapi-docs-link {
+  font-family: var(--mkapi-docs-link-font-family);
+  display: block;
+  float: right;
+}

src/mkapi/stylesheets/mkapi-material.css

@@ -0,0 +1,34 @@
+[data-md-color-scheme="default"],
+[data-md-color-scheme="slate"] {
+  --mkapi-heading-name-color: var(--md-default-fg-color--lighter);
+  --mkapi-object-border-color: var(--md-default-fg-color--light);
+  --mkapi-object-kind-color: var(--md-default-fg-color--light);
+  --mkapi-object-name-color: var(--md-code-hl-name-color);
+  --mkapi-object-name-font-family: var(--md-code-font-family);
+  --mkapi-prefix-color: var(--md-code-hl-name-color);
+  --mkapi-arg-color: var(--md-code-hl-name-color);
+  --mkapi-punctuation-color: var(--md-code-hl-punctuation-color);
+  --mkapi-variable-color: var(--md-code-hl-variable-color);
+  --mkapi-object-bases-color: var(--md-default-fg-color--light);
+  --mkapi-section-name-color: var(--md-default-fg-color);
+  --mkapi-section-border-color: var(--md-default-fg-color--light);
+  --mkapi-type-color: var(--md-code-hl-variable-color);
+  --mkapi-item-name-color: var(--md-default-fg-color);
+  --mkapi-example-bg-color: var(--md-code-bg-color);
+  --mkapi-docs-link-font-family: var(--md-text-font-family);
+}
+
+.md-typeset .admonition.deprecated,
+.md-typeset details.deprecated {
+  border-color: #ff5252;
+}
+.md-typeset .deprecated > .admonition-title,
+.md-typeset .deprecated > summary {
+  background-color: #ff52521a;
+}
+.md-typeset .deprecated > .admonition-title::before,
+.md-typeset .deprecated > summary::before {
+  background-color: #ff5252;
+  -webkit-mask-image: var(--md-admonition-icon--info);
+          mask-image: var(--md-admonition-icon--info);
+}

src/mkapi/templates/object.jinja2

@@ -1,4 +1,4 @@
-<div class="mkapi-container" markdown="1">
+<div class="mkapi-content" markdown="1">
 
 <{{ heading }} class="mkapi-heading" id="{{ obj.fullname }}" markdown="1">
 <span class="mkapi-heading-name">{{ fullname|safe }}</span>
@@ -38,7 +38,7 @@
 
 {% for section in doc.sections %}
 {%- if section.name and not section.kind -%}
-<div class="mkapi-section"><span class="mkapi-section-name">{{ section.name }}</span></div>
+<p class="mkapi-section"><span class="mkapi-section-name">{{ section.name }}</span></p>
 {%- endif %}
 
 {{ section.text.markdown|safe }}