asteria-ssg 1.0.0__tar.gz

asteria_ssg-1.0.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: asteria-ssg
+Version: 1.0.0
+Summary: Python SSG (Static Site Generator) based exclusively on ODT documents
+Author-email: "Diego C. Sampaio" <slavelix@ymail.com>
+License-Expression: AGPL-3.0-only
+Project-URL: Homepage, https://github.com/kriptolix/Asteria-Project
+Project-URL: Repository, https://github.com/kriptolix/Asteria-Project
+Project-URL: Issues, https://github.com/kriptolix/Asteria-Project/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Documentation
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: Jinja2>=3.1
+Requires-Dist: odt2web>=0.8
+Requires-Dist: MarkupSafe>=3.0.3
+Provides-Extra: watch
+Requires-Dist: watchfiles>=0.21; extra == "watch"
+
+# Asteria
+
+**Asteria** is a static site generator that builds your pages and blog posts
+straight from **OpenDocument Text (`.odt`)** files. Write in LibreOffice
+Writer, Word, or any ODT-compatible editor — Asteria converts it into a
+fast, themeable static site.
+
+> Looking for the full configuration reference? See
+> **[MANUAL.md](MANUAL.md)** for a complete guide covering every setting,
+> front matter field, and template variable.
+
+## Features
+
+- **Write in ODT, not Markdown.** Headings, lists, tables, and images
+  convert automatically — no learning curve for non-technical writers.
+- **Pages and posts**, with tags, categories, pagination, and RSS/Atom
+  feeds out of the box.
+- **Multi-language content.** Translate any page or post with a simple
+  filename convention; Asteria handles URL prefixes, per-language blog
+  indexes, feeds, and a ready-made language switcher.
+- **Cache-safe by default.** Static assets are automatically
+  content-hashed, so browsers never serve a stale CSS/JS file during
+  development or after a deploy.
+- **Internal cross-references** (`[[page-id]]`) between your own content,
+  validated at build time.
+- **Live-reloading dev server** (`asteria serve`) that rebuilds on save.
+- **Fully themeable** with plain Jinja2 templates.
+
+## Requirements
+
+- Python 3.11+
+
+## Installation
+
+```bash
+pip install asteria
+```
+
+*(or, from a local checkout: `pip install -e .`)*
+
+## Quick start
+
+```bash
+# Scaffold a new project (defaults to ./my_site if no path is given)
+asteria new my-blog
+cd my-blog
+
+# Serve locally with auto-rebuild on changes
+asteria serve
+# -> http://127.0.0.1:8000
+
+# Build the final static site
+asteria build
+```
+
+## Project structure
+
+```
+my-blog/
+└── source/
+    ├── site.yaml            # site configuration
+    ├── content/
+    │   ├── pages/            # standalone pages (*.odt)
+    │   └── posts/             # blog posts (*.odt)
+    ├── static/                # copied as-is to the site root
+    └── themes/
+        └── minimal/             # the active theme
+```
+
+`asteria build` writes the generated site to `my-blog/result/` by default.
+
+## Basic usage
+
+### Writing a page or post
+
+Create an `.odt` file under `content/pages/` or `content/posts/`. Start it
+with a front matter block, then write your content normally:
+
+```
+---
+title: My First Post
+date: 2024-03-15
+author: Jane Doe
+tags: hello, first-post
+---
+
+Welcome to my new blog! This is a regular paragraph, written like any
+other document in your ODT editor.
+```
+
+The filename (without extension) becomes the page's unique ID and, by
+default, its URL slug — `content/posts/my-first-post.odt` becomes
+`/blog/my-first-post/`.
+
+### Configuring your site
+
+Edit `source/site.yaml`:
+
+```yaml
+site:
+  title: "My Blog"
+  description: "Thoughts on things I like."
+  url: "https://myblog.example.com"
+  home_page: "welcome"
+
+blog:
+  posts_per_page: 10
+```
+
+You only need to set the keys you want to change — everything else falls
+back to sensible defaults. See **[MANUAL.md](MANUAL.md#6-configuration-siteyaml)**
+for the full list of options (multi-language setup, feeds, sitemap,
+URL patterns, asset fingerprinting, and more).
+
+### Linking to your own content
+
+```
+See the [[getting-started]] guide for more details.
+```
+
+### CLI commands
+
+| Command | What it does |
+|---|---|
+| `asteria new [path]` | Scaffold a new project (default: `./my_site`) |
+| `asteria build` | Build the full static site |
+| `asteria serve` | Build and serve locally, rebuilding on changes |
+| `asteria check` | Validate content and configuration without writing any files |
+| `asteria clean` | Remove the generated output (and optionally the build cache) |
+
+Run `asteria <command> --help` for all available flags.
+
+## Documentation
+
+The **[complete manual](MANUAL.md)** covers:
+
+- Every `site.yaml` option, with examples
+- Front matter reference
+- Multi-language content (i18n)
+- Internal references
+- Blog excerpts (`[[more]]`)
+- Asset fingerprinting / cache busting
+- Theming: required templates, available context variables, filters
+- Known limitations
+
+## License
+
+AGPL-3.0.
+
+## Contributing
+
+Issues and pull requests are welcome.

asteria_ssg-1.0.0/README.md

@@ -0,0 +1,152 @@
+# Asteria
+
+**Asteria** is a static site generator that builds your pages and blog posts
+straight from **OpenDocument Text (`.odt`)** files. Write in LibreOffice
+Writer, Word, or any ODT-compatible editor — Asteria converts it into a
+fast, themeable static site.
+
+> Looking for the full configuration reference? See
+> **[MANUAL.md](MANUAL.md)** for a complete guide covering every setting,
+> front matter field, and template variable.
+
+## Features
+
+- **Write in ODT, not Markdown.** Headings, lists, tables, and images
+  convert automatically — no learning curve for non-technical writers.
+- **Pages and posts**, with tags, categories, pagination, and RSS/Atom
+  feeds out of the box.
+- **Multi-language content.** Translate any page or post with a simple
+  filename convention; Asteria handles URL prefixes, per-language blog
+  indexes, feeds, and a ready-made language switcher.
+- **Cache-safe by default.** Static assets are automatically
+  content-hashed, so browsers never serve a stale CSS/JS file during
+  development or after a deploy.
+- **Internal cross-references** (`[[page-id]]`) between your own content,
+  validated at build time.
+- **Live-reloading dev server** (`asteria serve`) that rebuilds on save.
+- **Fully themeable** with plain Jinja2 templates.
+
+## Requirements
+
+- Python 3.11+
+
+## Installation
+
+```bash
+pip install asteria
+```
+
+*(or, from a local checkout: `pip install -e .`)*
+
+## Quick start
+
+```bash
+# Scaffold a new project (defaults to ./my_site if no path is given)
+asteria new my-blog
+cd my-blog
+
+# Serve locally with auto-rebuild on changes
+asteria serve
+# -> http://127.0.0.1:8000
+
+# Build the final static site
+asteria build
+```
+
+## Project structure
+
+```
+my-blog/
+└── source/
+    ├── site.yaml            # site configuration
+    ├── content/
+    │   ├── pages/            # standalone pages (*.odt)
+    │   └── posts/             # blog posts (*.odt)
+    ├── static/                # copied as-is to the site root
+    └── themes/
+        └── minimal/             # the active theme
+```
+
+`asteria build` writes the generated site to `my-blog/result/` by default.
+
+## Basic usage
+
+### Writing a page or post
+
+Create an `.odt` file under `content/pages/` or `content/posts/`. Start it
+with a front matter block, then write your content normally:
+
+```
+---
+title: My First Post
+date: 2024-03-15
+author: Jane Doe
+tags: hello, first-post
+---
+
+Welcome to my new blog! This is a regular paragraph, written like any
+other document in your ODT editor.
+```
+
+The filename (without extension) becomes the page's unique ID and, by
+default, its URL slug — `content/posts/my-first-post.odt` becomes
+`/blog/my-first-post/`.
+
+### Configuring your site
+
+Edit `source/site.yaml`:
+
+```yaml
+site:
+  title: "My Blog"
+  description: "Thoughts on things I like."
+  url: "https://myblog.example.com"
+  home_page: "welcome"
+
+blog:
+  posts_per_page: 10
+```
+
+You only need to set the keys you want to change — everything else falls
+back to sensible defaults. See **[MANUAL.md](MANUAL.md#6-configuration-siteyaml)**
+for the full list of options (multi-language setup, feeds, sitemap,
+URL patterns, asset fingerprinting, and more).
+
+### Linking to your own content
+
+```
+See the [[getting-started]] guide for more details.
+```
+
+### CLI commands
+
+| Command | What it does |
+|---|---|
+| `asteria new [path]` | Scaffold a new project (default: `./my_site`) |
+| `asteria build` | Build the full static site |
+| `asteria serve` | Build and serve locally, rebuilding on changes |
+| `asteria check` | Validate content and configuration without writing any files |
+| `asteria clean` | Remove the generated output (and optionally the build cache) |
+
+Run `asteria <command> --help` for all available flags.
+
+## Documentation
+
+The **[complete manual](MANUAL.md)** covers:
+
+- Every `site.yaml` option, with examples
+- Front matter reference
+- Multi-language content (i18n)
+- Internal references
+- Blog excerpts (`[[more]]`)
+- Asset fingerprinting / cache busting
+- Theming: required templates, available context variables, filters
+- Known limitations
+
+## License
+
+AGPL-3.0.
+
+## Contributing
+
+Issues and pull requests are welcome.

asteria_ssg-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "asteria-ssg"
+version = "1.0.0"
+description = "Python SSG (Static Site Generator) based exclusively on ODT documents"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "AGPL-3.0-only"
+
+authors = [
+    { name = "Diego C. Sampaio", email = "slavelix@ymail.com" }
+]
+
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",    
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",    
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Documentation",
+    "Topic :: Text Processing",
+]
+
+dependencies = [
+    "PyYAML>=6.0",
+    "Jinja2>=3.1",
+    "odt2web>=0.8",
+    "MarkupSafe>=3.0.3",
+]
+
+[project.optional-dependencies]
+watch = ["watchfiles>=0.21"]
+
+[project.scripts]
+asteria = "asteria.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["asteria*"]
+
+[tool.setuptools.package-data]
+asteria = ["site/**/*"]
+
+[project.urls]
+Homepage = "https://github.com/kriptolix/Asteria-Project"
+Repository = "https://github.com/kriptolix/Asteria-Project"
+Issues = "https://github.com/kriptolix/Asteria-Project/issues"

asteria_ssg-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

asteria_ssg-1.0.0/src/asteria/__init__.py

@@ -0,0 +1,3 @@
+"""Asteria — A Python Static Site Generator (SSG) whose only content source is ODT."""
+
+__version__ = "1.0.0"

asteria_ssg-1.0.0/src/asteria/api.py

@@ -0,0 +1,124 @@
+"""
+Public, frontend-agnostic API for Asteria.
+
+`cli.py` is a thin wrapper around this module. Any other frontend 
+(a GTK4 app, a script, a test) should
+import straight from here instead of going through the CLI or shelling
+out to `asteria ...` as a subprocess.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .build import BuildResult, run_build
+from .cache import clear_cache
+from .config import SiteConfig, load_config
+from .config import reset_theme as _reset_bundled_theme
+from .errors import AsteriaError
+from .scaffold import create_project
+from .server import (
+    DevServer,
+    DevServerStatus,
+    discover_watch_paths,
+    watch_backend_available,
+)
+from .writer import clean_output
+
+__all__ = [
+    "AsteriaError",
+    "BuildResult",
+    "SiteConfig",
+    "CleanResult",
+    "DevServer",
+    "DevServerStatus",
+    "build_project",
+    "check_project",
+    "clean_project",
+    "clear_project_cache",
+    "create_new_project",
+    "discover_watch_paths",
+    "load_project_config",
+    "reset_project_theme",
+    "watch_backend_available",
+]
+
+
+def load_project_config(project_root: Path, config_filename: str = "site.yaml") -> SiteConfig:
+    """Loads and returns a project's parsed `site.yaml` (merged with the
+    built-in defaults). Raises AsteriaError if the file is missing or not valid YAML.
+    """
+    return load_config(project_root / "source" / config_filename)
+
+
+def build_project(
+    project_root: Path,
+    converter_name: str = "odt2web",
+    config_filename: str = "site.yaml",
+) -> BuildResult:
+    """Runs a full build and writes the output to disk.   
+    """
+    return run_build(project_root, config_filename=config_filename, converter_name=converter_name)
+
+
+def check_project(
+    project_root: Path,
+    converter_name: str = "auto",
+    config_filename: str = "site.yaml",
+) -> BuildResult:
+    """Validates the project (YAML, ODT files, ids, references) without
+    writing anything to disk.
+    """
+    return run_build(
+        project_root,
+        config_filename=config_filename,
+        converter_name=converter_name,
+        dry_run=True,
+    )
+
+
+@dataclass
+class CleanResult:
+    """What `clean_project` actually did, so a UI can report it without
+    re-deriving it from a SiteConfig itself."""
+
+    output_dir: Path
+    output_removed: bool
+    cache_removed: bool
+
+
+def clean_project(
+    project_root: Path,
+    remove_cache: bool = False,
+    config_filename: str = "site.yaml",
+) -> CleanResult:
+    """Removes the generated site (`config.output_dir`) and, optionally,
+    the incremental conversion cache.
+    """
+    config = load_config(project_root / "source" / config_filename)
+    output_removed = config.output_dir.exists()
+    clean_output(config)
+    cache_removed = remove_cache and clear_cache(project_root)
+    return CleanResult(
+        output_dir=config.output_dir,
+        output_removed=output_removed,
+        cache_removed=cache_removed,
+    )
+
+
+def clear_project_cache(project_root: Path) -> bool:
+    
+    return clear_cache(project_root)
+
+
+def create_new_project(target_dir: Path) -> list[str]:
+    
+    return create_project(target_dir)
+
+
+def reset_project_theme(project_root: Path) -> Path:
+    """Overwrites `source/themes/minimal` with Asteria's bundled
+    'minimal' theme, discarding any local edits to it.
+    """
+    return _reset_bundled_theme(project_root)