maatlog 0.0.0__tar.gz

maatlog-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 usaturn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maatlog-0.0.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: maatlog
+Version: 0.0.0
+Summary: A Sphinx extension that turns documentation projects into static blogs.
+Author: usaturn
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: Sphinx :: Extension
+Requires-Dist: sphinx>=9.1
+Requires-Dist: myst-parser>=5.1
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/usaturn/maatlog
+Description-Content-Type: text/x-rst
+
+MaatLog
+=======
+
+MaatLog is a Sphinx extension that turns a documentation project into a static
+blog. Posts are ordinary reStructuredText or MyST Markdown documents with a
+small metadata schema. MaatLog adds archives, taxonomy navigation, Atom feeds,
+and an HTML Theme API on top of Sphinx's public extension surface.
+
+Requirements
+------------
+
+* Python 3.14+
+* Sphinx 9.1+
+* myst-parser 5.1+
+
+Install
+-------
+
+From a built distribution (wheel or sdist)::
+
+    pip install maatlog
+
+Or from a checkout with `uv`::
+
+    uv sync
+    uv pip install -e .
+
+Quick start
+-----------
+
+1. Enable the extension and (optionally) the bundled theme in ``conf.py``::
+
+    extensions = ["maatlog"]
+
+    html_theme = "maatlog-default"
+    html_baseurl = "https://example.com/"  # required when Atom feeds are enabled
+
+    maatlog_timezone = "UTC"
+    maatlog_tags = {"sphinx": "Sphinx", "python": "Python"}
+    maatlog_categories = {"engineering": "Engineering"}
+    maatlog_authors = {"alice": "Alice"}
+
+2. Write a reStructuredText post (field list before the title)::
+
+    :maatlog-post: true
+    :maatlog-published-at: 2026-08-01T09:00:00+09:00
+    :maatlog-slug: hello-maatlog
+    :maatlog-tags: sphinx, python
+    :maatlog-categories: engineering
+    :maatlog-authors: alice
+    :maatlog-excerpt: First post with MaatLog.
+
+    Hello MaatLog
+    =============
+
+    Body of the post…
+
+3. Or an equivalent MyST Markdown post (YAML front matter)::
+
+    ---
+    maatlog-post: true
+    maatlog-published-at: 2026-08-01T09:00:00+09:00
+    maatlog-slug: hello-maatlog
+    maatlog-tags: [sphinx, python]
+    maatlog-categories: [engineering]
+    maatlog-authors: [alice]
+    maatlog-excerpt: First post with MaatLog.
+    ---
+
+    # Hello MaatLog
+
+    Body of the post…
+
+4. Build HTML::
+
+    sphinx-build -b html sourcedir builddir
+
+With the defaults above, MaatLog generates:
+
+* Post pages using the selected MaatLog theme
+* Archives under ``blog/`` (configurable via ``maatlog_archive_docname``)
+* Atom feeds under the archive root (when ``maatlog_generate_feeds`` is true)
+* Cross-reference roles such as ``:maatlog:post:``, ``:maatlog:tag:``, and friends
+
+Rebuild notes
+-------------
+
+Most ``maatlog_*`` settings rebuild the Sphinx environment (``env``). Feed-related
+settings rebuild HTML outputs only (``html``). After changing taxonomy
+dictionaries, archive root, page size, timezone, or feed options, run a clean
+or full rebuild so archives and feeds stay consistent.
+
+``SOURCE_DATE_EPOCH`` (Unix seconds, UTC) freezes the build clock used for
+draft / scheduled / expired publication status. Prefer it for reproducible CI
+builds.
+
+What MaatLog does not replace
+-----------------------------
+
+MaatLog does not replace Sphinx document titles, toctree, search, autodoc,
+Pygments, or intersphinx. Ordinary documentation pages coexist with posts in
+the same project. Full HTML features (archives, Theme API validation, feeds,
+MaatLog HTML metadata) are guaranteed for the ``html`` and ``dirhtml`` builders
+only; other builders keep post body and role resolution where applicable.
+
+Documentation
+-------------
+
+* `docs/authoring.rst` — post metadata schema and examples
+* `docs/configuration.rst` — conf.py settings and defaults
+* `docs/theme-api.rst` — Theme API 1.0 contract and official themes
+* `docs/builders.rst` — builder matrix and static-site constraints
+
+Development
+-----------
+
+Clone the repository, install the locked development environment, and run the
+shared verification entrypoint::
+
+    uv sync --locked --all-groups
+    ./scripts/ci/verify.sh full
+
+License and status
+------------------
+
+MaatLog MVP targets Sphinx-based static blogs. Public metadata keys, config
+names, roles, the Theme API major version, generated docname rules, and
+diagnostic codes are compatibility-managed surfaces.

maatlog-0.0.0/README.rst

@@ -0,0 +1,128 @@
+MaatLog
+=======
+
+MaatLog is a Sphinx extension that turns a documentation project into a static
+blog. Posts are ordinary reStructuredText or MyST Markdown documents with a
+small metadata schema. MaatLog adds archives, taxonomy navigation, Atom feeds,
+and an HTML Theme API on top of Sphinx's public extension surface.
+
+Requirements
+------------
+
+* Python 3.14+
+* Sphinx 9.1+
+* myst-parser 5.1+
+
+Install
+-------
+
+From a built distribution (wheel or sdist)::
+
+    pip install maatlog
+
+Or from a checkout with `uv`::
+
+    uv sync
+    uv pip install -e .
+
+Quick start
+-----------
+
+1. Enable the extension and (optionally) the bundled theme in ``conf.py``::
+
+    extensions = ["maatlog"]
+
+    html_theme = "maatlog-default"
+    html_baseurl = "https://example.com/"  # required when Atom feeds are enabled
+
+    maatlog_timezone = "UTC"
+    maatlog_tags = {"sphinx": "Sphinx", "python": "Python"}
+    maatlog_categories = {"engineering": "Engineering"}
+    maatlog_authors = {"alice": "Alice"}
+
+2. Write a reStructuredText post (field list before the title)::
+
+    :maatlog-post: true
+    :maatlog-published-at: 2026-08-01T09:00:00+09:00
+    :maatlog-slug: hello-maatlog
+    :maatlog-tags: sphinx, python
+    :maatlog-categories: engineering
+    :maatlog-authors: alice
+    :maatlog-excerpt: First post with MaatLog.
+
+    Hello MaatLog
+    =============
+
+    Body of the post…
+
+3. Or an equivalent MyST Markdown post (YAML front matter)::
+
+    ---
+    maatlog-post: true
+    maatlog-published-at: 2026-08-01T09:00:00+09:00
+    maatlog-slug: hello-maatlog
+    maatlog-tags: [sphinx, python]
+    maatlog-categories: [engineering]
+    maatlog-authors: [alice]
+    maatlog-excerpt: First post with MaatLog.
+    ---
+
+    # Hello MaatLog
+
+    Body of the post…
+
+4. Build HTML::
+
+    sphinx-build -b html sourcedir builddir
+
+With the defaults above, MaatLog generates:
+
+* Post pages using the selected MaatLog theme
+* Archives under ``blog/`` (configurable via ``maatlog_archive_docname``)
+* Atom feeds under the archive root (when ``maatlog_generate_feeds`` is true)
+* Cross-reference roles such as ``:maatlog:post:``, ``:maatlog:tag:``, and friends
+
+Rebuild notes
+-------------
+
+Most ``maatlog_*`` settings rebuild the Sphinx environment (``env``). Feed-related
+settings rebuild HTML outputs only (``html``). After changing taxonomy
+dictionaries, archive root, page size, timezone, or feed options, run a clean
+or full rebuild so archives and feeds stay consistent.
+
+``SOURCE_DATE_EPOCH`` (Unix seconds, UTC) freezes the build clock used for
+draft / scheduled / expired publication status. Prefer it for reproducible CI
+builds.
+
+What MaatLog does not replace
+-----------------------------
+
+MaatLog does not replace Sphinx document titles, toctree, search, autodoc,
+Pygments, or intersphinx. Ordinary documentation pages coexist with posts in
+the same project. Full HTML features (archives, Theme API validation, feeds,
+MaatLog HTML metadata) are guaranteed for the ``html`` and ``dirhtml`` builders
+only; other builders keep post body and role resolution where applicable.
+
+Documentation
+-------------
+
+* `docs/authoring.rst` — post metadata schema and examples
+* `docs/configuration.rst` — conf.py settings and defaults
+* `docs/theme-api.rst` — Theme API 1.0 contract and official themes
+* `docs/builders.rst` — builder matrix and static-site constraints
+
+Development
+-----------
+
+Clone the repository, install the locked development environment, and run the
+shared verification entrypoint::
+
+    uv sync --locked --all-groups
+    ./scripts/ci/verify.sh full
+
+License and status
+------------------
+
+MaatLog MVP targets Sphinx-based static blogs. Public metadata keys, config
+names, roles, the Theme API major version, generated docname rules, and
+diagnostic codes are compatibility-managed surfaces.

maatlog-0.0.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "maatlog"
+version = "0.0.0"
+description = "A Sphinx extension that turns documentation projects into static blogs."
+readme = "README.rst"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Framework :: Sphinx :: Extension",
+]
+dependencies = [
+    "Sphinx>=9.1",
+    "myst-parser>=5.1",
+    "pydantic>=2",
+]
+
+[[project.authors]]
+name = "usaturn"
+
+[project.urls]
+Homepage = "https://github.com/usaturn/maatlog"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff",
+    "pyright",
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+    "tools/public_sync/tests",
+]
+pythonpath = ["tests"]
+addopts = ["--import-mode=importlib"]
+
+[tool.pyright]
+pythonVersion = "3.14"
+typeCheckingMode = "strict"
+include = [
+    "src",
+    "tests",
+    "tools/public_sync",
+]
+
+[tool.ruff]
+target-version = "py314"
+extend-exclude = ["*.md"]
+line-length = 119
+
+[tool.ruff.lint]
+select = [
+    "F",
+    "B",
+    "I",
+    "E",
+    "W",
+]
+ignore = []
+fixable = ["ALL"]
+
+[tool.ruff.format]
+line-ending = "auto"

maatlog-0.0.0/pyproject.toml.orig

@@ -0,0 +1,64 @@
+[project]
+name = "maatlog"
+version = "0.0.0"
+description = "A Sphinx extension that turns documentation projects into static blogs."
+readme = "README.rst"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "usaturn" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Framework :: Sphinx :: Extension",
+]
+dependencies = ["Sphinx>=9.1", "myst-parser>=5.1", "pydantic>=2"]
+
+[project.urls]
+Homepage = "https://github.com/usaturn/maatlog"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest", "ruff", "pyright"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "tools/public_sync/tests"]
+pythonpath = ["tests"]
+addopts = ["--import-mode=importlib"]
+
+[tool.pyright]
+pythonVersion = "3.14"
+typeCheckingMode = "strict"
+include = ["src", "tests", "tools/public_sync"]
+
+
+[tool.ruff]
+target-version = "py314"
+# ruff 既定の除外リストを保ちつつ追加する（公式は exclude ではなく extend-exclude を推奨）
+# .venv と .ruff_cache は既定に含まれるため個別指定は不要
+extend-exclude = [
+    "*.md",    # ruff 0.16+ は Markdown 内コードブロックを整形するため除外
+]
+line-length = 119
+
+[tool.ruff.lint]
+select = [
+    "F", # Flake8
+    "B", # Black
+    "I", # isort
+    "E", # error
+    "W"  # warning
+]
+ignore = []
+fixable = ["ALL"]
+
+# 自動フォーマット設定
+[tool.ruff.format]
+#quote-style = "double"
+#indent-style = "space"
+#skip-magic-trailing-comma = false
+line-ending = "auto"

maatlog-0.0.0/src/maatlog/__init__.py

@@ -0,0 +1,3 @@
+from .extension import setup
+
+__all__ = ["setup"]

maatlog-0.0.0/src/maatlog/_myst_compat.py

@@ -0,0 +1,80 @@
+"""Narrow compatibility adapter for typed MyST 5.1 front matter."""
+
+from collections.abc import Callable, Mapping
+from importlib import import_module
+from typing import Protocol, cast
+
+from myst_parser.config.main import TopmatterReadError, read_topmatter
+
+
+class _Mark(Protocol):
+    line: int
+
+
+class _ScalarNode(Protocol):
+    value: object
+    start_mark: _Mark
+
+
+class _MappingNode(Protocol):
+    value: list[tuple[_ScalarNode, object]]
+
+
+class _YamlModule(Protocol):
+    compose: Callable[[str], object | None]
+
+
+class _MySTRendererModule(Protocol):
+    yaml: _YamlModule
+
+
+def read_typed_frontmatter(source: str) -> dict[str, tuple[object, int]] | None:
+    """Return MyST front matter values and one-based key lines.
+
+    ``read_topmatter`` is MyST's own typed loader. MyST's renderer module owns
+    the YAML implementation used to turn the same payload into marked nodes;
+    keeping that access here prevents MaatLog from importing transitive PyYAML
+    directly and gives diagnostics the parser's key marks.
+    """
+
+    try:
+        topmatter = read_topmatter(source)
+    except TopmatterReadError:
+        return None
+    if topmatter is None:
+        return None
+
+    payload = _frontmatter_payload(source)
+    renderer = cast(_MySTRendererModule, cast(object, import_module("myst_parser.mdit_to_docutils.base")))
+    root = renderer.yaml.compose(payload)
+    key_lines = _mapping_key_lines(root)
+    typed = cast(Mapping[object, object], topmatter)
+    return {
+        key: (value, key_lines.get(key, 1))
+        for key, value in typed.items()
+        if isinstance(key, str) and key.startswith("maatlog-")
+    }
+
+
+def _frontmatter_payload(source: str) -> str:
+    lines = source.splitlines()
+    if not lines or not lines[0].startswith("---"):
+        return ""
+    payload: list[str] = []
+    for line in lines[1:]:
+        if line.startswith(("---", "...")):
+            break
+        payload.append(line)
+    return "\n".join(payload) + ("\n" if payload else "")
+
+
+def _mapping_key_lines(root: object | None) -> dict[str, int]:
+    if root is None or not hasattr(root, "value"):
+        return {}
+    mapping = cast(_MappingNode, root)
+    lines: dict[str, int] = {}
+    for key_node, _ in mapping.value:
+        if isinstance(key_node.value, str):
+            # The payload begins on source line 2, while parser marks are zero-based.
+            lines[key_node.value] = key_node.start_mark.line + 2
+    return lines