texsmith 0.0.2.dev0__tar.gz

texsmith-0.0.2.dev0/.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+indent_size = 4

texsmith-0.0.2.dev0/.github/workflows/ci.yml

@@ -0,0 +1,239 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+    tags: ["v*"]
+  pull_request:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  lint:
+    name: Ruff (lint + format check)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-python: false
+        env:
+          UV_CACHE_SAVE: "false"
+
+      - name: Sync dependencies (dev + docs)
+        run: uv sync --all-groups --frozen
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format . --check
+
+  tests:
+    name: Pytest matrix
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13", "3.14"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-python: false
+        env:
+          UV_CACHE_SAVE: "false"
+
+      - name: Sync dependencies (dev + docs)
+        run: uv sync --all-groups --frozen
+
+      - name: Run pytest
+        run: uv run pytest
+
+  build-artifacts:
+    name: Build dists & docs
+    needs: [lint, tests]
+    runs-on: ubuntu-latest
+    env:
+      PLAYWRIGHT_BROWSERS_PATH: /home/runner/.cache/texsmith/playwright/browsers
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      # Checkout repository
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Install system dependencies (Playwright, cairo, etc.)
+      - name: Install system dependencies
+        run: |
+          sudo apt-get install -y libglib2.0-0 libnspr4 libnss3 libatk1.0-0 \
+          libatk-bridge2.0-0 libcups2 libxkbcommon0 libatspi2.0-0 libxcomposite1 \
+          libxdamage1 libxfixes3 libxrandr2 libgbm1 libcairo2 libpango-1.0-0
+
+      # Install uv
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-python: false
+
+      # Install full dependency set
+      - name: Sync dependencies (dev + docs)
+        run: uv sync --all-groups --frozen
+
+      # Install Playwright browser binaries + system deps
+      - name: Install Playwright browsers
+        run: |
+          uv run playwright install-deps
+          uv run playwright install chromium
+
+      # Build all examples (clean + all)
+      - name: Build examples
+        run: |
+          make examples
+
+      # Package example PDFs into a single archive
+      - name: Package example PDFs
+        run: |
+          mkdir -p examples
+          zip -j examples/examples.zip examples/build/*.pdf
+
+      # Build MkDocs HTML documentation
+      - name: Build documentation (HTML + LaTeX)
+        run: |
+          make docs
+
+      # Build the main Python package distribution
+      - name: Build distributions (texsmith)
+        run: uv build
+
+      # Build the MkDocs plugin distribution
+      - name: Build distributions (mkdocs_texsmith)
+        working-directory: packages/mkdocs_texsmith
+        run: uv build
+
+      # Upload all artifacts needed for the release job
+      - name: Upload release artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: texsmith-release-assets
+          path: |
+            dist/*
+            packages/mkdocs_texsmith/dist/*
+            press/texsmith-docs/texsmith-docs.pdf
+            examples/examples.zip
+          if-no-files-found: error
+
+  release:
+    name: Release (Docs + PyPI)
+    needs: [build-artifacts]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write       # Required for GitHub Pages and GitHub Releases
+      id-token: write
+      pages: write
+      actions: read
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/texsmith/
+
+    steps:
+      # Checkout repository (needed by mike deploy)
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Download all build artifacts generated previously
+      - name: Download release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: texsmith-release-assets
+          path: .
+
+      # Place artifacts at repository root where publish steps expect them
+      - name: Unpack release artifacts
+        run: |
+          set -euo pipefail
+          if [ -d texsmith-release-assets ]; then
+            shopt -s dotglob
+            mv texsmith-release-assets/* .
+            rmdir texsmith-release-assets
+          fi
+
+      # Ensure expected paths exist for publish steps (artifact layout may vary)
+      - name: Normalize artifact paths
+        run: |
+          set -euo pipefail
+          mkdir -p packages/mkdocs_texsmith/dist
+          shopt -s nullglob
+          # If plugin dists landed at repo root or under dist/, move them into the expected folder.
+          for f in mkdocs_texsmith-* mkdocs-texsmith-* dist/mkdocs_texsmith-* dist/mkdocs-texsmith-*; do
+            [ -e "$f" ] || continue
+            dest="packages/mkdocs_texsmith/dist/$(basename "$f")"
+            mv "$f" "$dest"
+          done
+      # Install uv for deploying the docs
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-python: false
+        env:
+          UV_CACHE_SAVE: "false"
+
+      # Publish versioned documentation to GitHub Pages using mike
+      - name: Publish documentation to GitHub Pages (mike)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          VERSION="${GITHUB_REF_NAME#v}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git fetch origin gh-pages || true
+          uv sync --group docs --frozen
+          uv run mike deploy --push --branch gh-pages --remote origin --update-aliases "$VERSION" latest
+          uv run mike set-default --push --branch gh-pages --remote origin latest
+
+      # Publish the package to PyPI from prebuilt dists
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      # Publish the MkDocs plugin to PyPI from prebuilt dists
+      - name: Publish mkdocs-texsmith package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: packages/mkdocs_texsmith/dist
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      # create a GitHub Release and attach artifacts
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*
+            packages/mkdocs_texsmith/dist/*
+            press/texsmith-docs/texsmith-docs.pdf
+            examples/examples.zip

texsmith-0.0.2.dev0/.gitignore

@@ -0,0 +1,59 @@
+# Python artifacts
+__pycache__/
+.DS_Store
+.ruff_cache/
+.uv-cache/
+.venv
+*.egg-info/
+*.pyc
+*.pyd
+*.pyo
+*.swo
+*.swp
+
+# LaTeX artifacts
+*_minted-*/
+*.acn
+*.acr
+*.alg
+*.aux
+*.bcf
+*.fdb_latexmk
+*.fls
+*.glg
+*.glo
+*.gls
+*.glsdefs
+*.idx
+*.ilg
+*.ind
+*.ist
+*.listing
+*.lof
+*.log
+*.lol
+*.lot
+*.maf
+*.mtc*
+*.mypyg
+*.run.xml
+*.synctex.gz
+*.toc
+*.xdv
+
+# Local build artifacts
+build*/
+*:Zone.Identifier
+tmp*
+.uv_cache/
+examples/diagrams/*.pdf
+press/
+site/
+docs/assets/examples/*.png
+docs/assets/examples/*.pdf
+.coverage
+*.meta
+
+.texsmith/
+
+*_build/

texsmith-0.0.2.dev0/.vscode/settings.json

@@ -0,0 +1,26 @@
+{
+  // Sélection de l'interpréteur
+  "python.defaultInterpreterPath": ".venv/bin/python",
+
+  // Pylance/Pyright
+  "python.languageServer": "Pylance",
+  "python.analysis.inlayHints.variableTypes": true,
+  "python.analysis.inlayHints.functionReturnTypes": true,
+
+  // Ruff = linter + (optionnel) formateur + organise imports
+  "ruff.enable": true,
+  "ruff.lint.enable": true,
+  "ruff.nativeServer": true,
+
+  "ruff.organizeImports": true,
+
+  "[python]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  },
+  "python.testing.pytestArgs": [
+    "."
+  ],
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true
+}

texsmith-0.0.2.dev0/AGENT.md

@@ -0,0 +1,36 @@
+# TeXSmith Agent Guide
+
+## Architecture Overview
+
+- Flow: `texsmith.ui.cli` (Typer) and library calls both funnel into `api.ConversionService`, which splits inputs/front matter/bibliography, prepares `Document` objects, and drives the render pipeline.
+- Document model: `api.document.Document` stores normalised HTML + front matter + slot directives; `DocumentRenderOptions` controls heading offsets/numbering/title handling; slot selectors merge CLI/front matter values.
+- Render engine: `core.conversion` builds `RenderContext/DocumentContext`, then runs `adapters.handlers` in `RenderPhase` order (PRE/BLOCK/INLINE/POST) to rewrite the BeautifulSoup tree, emit LaTeX fragments, and register assets; asset hashing/manifests live in `_assets`.
+- Templates: `core.templates` + `api.templates` load template runtimes, slots, bindings, and overrides; `TemplateSession`/`TemplateRenderer` assemble slot bundles and LaTeX scaffolding; template language resolution supports builtins and user paths.
+- Fragments: `core.fragments` orchestrates fragment metadata/injection; builtin fragments under `fragments/*` (ts-geometry, ts-typesetting, ts-fonts, ts-extra, ts-keystrokes, ts-callouts, ts-code, ts-glossary, ts-index, ts-bibliography, ts-todolist) populate template slots.
+- Engines: `adapters.latex.engines` resolves Tectonic/latexmk (plus biber makeindex helpers), builds command/env args, and can run via Docker when configured; formatter/pygments handle LaTeX-safe code blocks.
+- Extensions/plugins: `adapters.plugins` (Material/snippet) and `extensions` (progress bar, texlogos, index helpers) extend Markdown parsing or LaTeX output; `adapters.transformers` hosts diagram converters (mermaid/drawio), strategies, and helpers.
+- Assets/fonts: `fonts` caches/embed OpenMoji/Noto; asset registry ensures template and diagram assets are copied or hashed when `copy_assets`/`convert_assets`/`hash_assets` flags are set.
+
+## Design Principles
+
+Always adhere to these principles:
+
+- Composition over inheritance.
+- Modules can inject, extend, and redefine functionality.
+- Modules remain deterministic through topological ordering.
+- Modules foster reusability and remixing.
+- Modules cooperate through well-defined contracts.
+- limit scope to demonstrated needs; keep public interfaces clear.
+- **NEVER** add shims or temporary fixes; refactor instead.
+- **NEVER** introduce technical debt; address issues immediately.
+- **NEVER** duplicate code; abstract and reuse existing functionality.
+- **NEVER** introduce compatibility layers; maintain a single, clear implementation.
+
+## Working agreements
+
+- Always run `uv run pytest` after modifying Python code.
+- Follow coding principles: SOLID, YAGNI, SSOT, KISS and design principles.
+- Always run `uv run ruff format .` and `uv run ruff check .` after changing Python files.
+- Maintain clear and concise documentation for all features added or modified.
+- Use type hints for all functions and methods.
+- Write unit tests for new features and bug fixes.

texsmith-0.0.2.dev0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/)
+and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Created an explicit changelog to track the rewritten Git history.
+- Documented the new fragment manifest (attributes + partials + required_partials), partial precedence (template > fragment > core), and conversion pipeline order.
+- Expanded template discovery docs and CLI info output (slots, fragments, attribute columns).
+- Marked the legacy ``texsmith.fragments`` import path as deprecated; fragments should rely on ``fragment.toml`` or entrypoint factories.
+- Dropped unused template knobs (article twocolumn/preamble hooks, letter callout_style stub) to align manifests with the refactored pipeline.
+
+### Changed
+
+- Updated every reference to the scientific paper demo so that it matches the
+  renamed `examples/paper` directory used by the CLI tests and documentation.
+- Template lookup now prefers built-ins, then `texsmith-template-*` packages/entry points, then cwd/parents, then `~/.texsmith/templates`; explicit paths still bypass discovery.
+- Built-in template docs reflect appendix slot ordering and removal of legacy cover/twocolumn/backmatter/emoji attributes.
+
+## [0.3.0] - 2025-11-17
+
+### Added
+
+- Imported the Carauma article template, EPFL thesis scaffolding, and the book
+  template migration.
+- Published the MkDocs site content together with lint rules for Markdown and
+  prettier formatting of documentation.
+- Introduced the MkDocs plugin workspace, PDF press kit example, and CI coverage
+  reporting defaults.
+
+### Changed
+
+- Hardened the bibliography pipeline, slot handling, and document renderer to
+  better support mermaid diagrams, smart typography, and press metadata.
+- Expanded the builtin templates (article, book, letter) with fonts, abstract
+  slots, syntax-highlighted code blocks, and typography refinements.
+
+### Fixed
+
+- Addressed numerous CLI issues (slot injection, latexmkrc, todolist/biber
+  warnings) and ensured `pyproject.toml` references non-editable workspace
+  installs.
+- Resolved regressions in the book template migration and documentation builds.
+
+## [0.2.0] - 2025-10-27
+
+### Added
+
+- Completed the six-step core refactor: `texsmith.core` now owns the conversion
+  service, template orchestration, diagnostics emitters, and document slots.
+- Added multi-document CLI rendering, pylatexenc integration, MkDocs example
+  projects, and a comprehensive regression test suite (CLI, MkDocs, templates,
+  extensions).
+- Introduced additional LaTeX extensions (acronyms, index generation, texlogos,
+  bibliography improvements) and shipped assets such as the TeXSmith logo,
+  docker adapters, and draw.io support.
+
+### Changed
+
+- Reworked bibliography handling, latex adapters, utility modules, and template
+  manifests to match the new orchestration pipeline.
+- Migrated existing templates to the new structure, moved partials into package
+  modules, and refreshed documentation with dark-mode assets.
+
+### Fixed
+
+- Numerous formatting, ruff, and CI fixes plus better caching/performance in the
+  renderer, docker adapter, and media pipeline.
+
+## [0.1.0] - 2025-10-21
+
+### Added
+
+- Initial TeXSmith CLI implementation with LaTeX adapters, slot-aware templates,
+  bibliography/config helpers, and end-to-end article rendering examples.
+- Early documentation, MkDocs integration, and helper scripts for generating the
+  cheese/scientific paper demonstration.

texsmith-0.0.2.dev0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Isaac Muse
+
+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.

texsmith-0.0.2.dev0/Makefile

@@ -0,0 +1,20 @@
+PRE_CMD := uv run
+
+examples:
+	cd examples && $(PRE_CMD) make all
+
+artifacts:
+	./scripts/refresh_cli_help.sh
+
+docs: artifacts
+	TEXSMITH_BUILD=1 $(PRE_CMD) mkdocs build
+
+lint:
+	$(PRE_CMD) ruff format .
+	$(PRE_CMD) ruff check .
+	$(PRE_CMD) ruff format .
+
+clean:
+	$(RM) -rf build press site
+
+.PHONY: examples artifacts docs clean lint