article-cli 1.3.2__tar.gz → 2.0.0__tar.gz

{article_cli-1.3.2 → article_cli-2.0.0}/.gitignore

@@ -27,6 +27,16 @@ share/python-wheels/
 *.egg
 MANIFEST
 
+# Node / Antora documentation
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Generated/downloaded font assets
+fonts/
+fonts-test/
+
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
@@ -139,4 +149,4 @@ dmypy.json
 Thumbs.db
 
 # Test configurations
-test-config.toml
+test-config.toml

{article_cli-1.3.2 → article_cli-2.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: article-cli
-Version: 1.3.2
-Summary: CLI tool for managing LaTeX articles with git integration and Zotero bibliography
+Version: 2.0.0
+Summary: CLI tool for managing LaTeX and Typst documents with git integration and Zotero bibliography
 Project-URL: Homepage, https://github.com/feelpp/article.cli
 Project-URL: Documentation, https://github.com/feelpp/article.cli#readme
 Project-URL: Repository, https://github.com/feelpp/article.cli.git
@@ -29,27 +29,32 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
 License-File: LICENSE
-Keywords: academic,bibliography,git,latex,research,zotero
+Keywords: academic,bibliography,git,latex,presentations,research,typst,zotero
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Text Processing :: Markup :: LaTeX
-Requires-Python: >=3.8
+Requires-Python: >=3.9
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.28.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
 Provides-Extra: dev
-Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: black==25.11.0; extra == 'dev'
+Requires-Dist: build>=1.2.0; extra == 'dev'
 Requires-Dist: flake8>=6.0; extra == 'dev'
-Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: mypy<2.0,>=1.0; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
 Requires-Dist: types-requests; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -59,28 +64,31 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://badge.fury.io/py/article-cli.svg)](https://badge.fury.io/py/article-cli)
 [![Python Support](https://img.shields.io/pypi/pyversions/article-cli.svg)](https://pypi.org/project/article-cli/)
 
-A command-line tool for managing LaTeX articles and presentations with git integration and Zotero bibliography synchronization.
+A command-line tool for managing LaTeX and Typst documents with git integration and Zotero bibliography synchronization.
 
 ## Features
 
-- **Repository Initialization**: Complete setup for LaTeX article or presentation projects with one command
-- **Project Types**: Support for articles, Beamer presentations, and posters
+- **Repository Initialization**: Complete setup for LaTeX or Typst projects with one command
+- **Project Types**: Support for articles, Beamer presentations, posters, and Typst documents
 - **LaTeX Compilation**: Compile documents with latexmk/pdflatex/xelatex/lualatex, watch mode, shell escape support
+- **Typst Compilation**: Full support for Typst documents with watch mode and custom font paths
 - **Font Installation**: Download and install fonts for XeLaTeX projects (Marianne, Roboto Mono, etc.)
 - **GitHub Actions Workflows**: Automated PDF compilation with XeLaTeX support, artifact upload, and GitHub releases
 - **Git Release Management**: Create, list, and delete releases with gitinfo2 support
 - **Zotero Integration**: Synchronize bibliography from Zotero with robust pagination and error handling
+- **Lifecycle Commands**: Use `init`, `setup`, `doctor`, `bib update`, `compile`, `version`, and `release`
 - **LaTeX Build Management**: Clean build files and manage LaTeX compilation artifacts
 - **Git Hooks Setup**: Automated setup of git hooks for gitinfo2 integration
+- **Repository Diagnostics**: `doctor` checks for git, hooks, build tools, Zotero, workflows, release readiness, and safe repairs with `--fix`
 - **Project Configuration**: Auto-generates pyproject.toml with article-cli settings
-- **Documentation**: Creates README with build instructions and usage guide
+- **Documentation**: Creates project README files and ships an Antora documentation site
 
 ## Installation
 
 ### From PyPI (recommended)
 
 ```bash
-pip install article-cli
+uv tool install article-cli
 ```
 
 ### From Source
@@ -88,9 +96,32 @@ pip install article-cli
 ```bash
 git clone https://github.com/feelpp/article.cli.git
 cd article.cli
-pip install -e .
+uv sync --all-extras --dev
+uv run article-cli --help
 ```
 
+### Development Commands
+
+```bash
+uv sync --all-extras --dev
+uv run pytest
+uv run black --check src tests
+uv run mypy src
+uv build
+```
+
+### Documentation Site
+
+The documentation site is built with Antora and the Feel++ Antora UI bundle:
+
+```bash
+npm install
+npm run docs:build
+npm run docs:preview
+```
+
+The generated site is written to `build/site`.
+
 ## Quick Start
 
 ### For New Projects
@@ -116,8 +147,12 @@ pip install -e .
 
 3. **Setup git hooks and update bibliography**:
    ```bash
+   article-cli doctor
+   article-cli doctor --fix
+   article-cli setup --dry-run
    article-cli setup
-   article-cli update-bibtex
+   article-cli bib update --dry-run
+   article-cli bib update
    ```
 
 4. **Commit and push** to trigger automated PDF compilation!
@@ -126,6 +161,8 @@ pip install -e .
 
 1. **Setup git hooks** (run once per repository):
    ```bash
+   article-cli doctor
+   article-cli doctor --fix
    article-cli setup
    ```
 
@@ -137,12 +174,15 @@ pip install -e .
 
 3. **Update bibliography from Zotero**:
    ```bash
-   article-cli update-bibtex
+   article-cli bib update
    ```
 
-4. **Create a release**:
+4. **Compile, refresh version metadata, and create a release**:
    ```bash
-   article-cli create v1.0.0
+   article-cli compile
+   article-cli version
+   article-cli release v1.0.0 --dry-run
+   article-cli release v1.0.0
    ```
 
 ## Configuration
@@ -165,9 +205,18 @@ group_id = "4678293"  # Default for article.template
 output_file = "references.bib"
 
 [git]
-auto_push = true
+auto_push = false
 default_branch = "main"
 
+[workflow]
+runner_policy = "github"
+github_runner = "ubuntu-24.04"
+self_hosted_label = "self-texlive"
+self_hosted_org = ""
+bibliography = "off"
+release = "github"
+artifact_includes = []
+
 [latex]
 clean_extensions = [".aux", ".bbl", ".blg", ".log", ".out", ".synctex.gz"]
 
@@ -186,8 +235,13 @@ directory = "."
 # url = "https://example.com/theme.zip"
 # description = "My custom theme"
 # files = ["beamerthememytheme.sty"]
+# typst_files = ["mytheme.typ"]
 # requires_fonts = false
 # engine = "pdflatex"
+
+[typst]
+font_paths = ["fonts/", "~/.fonts/"]
+build_dir = "build"
 ```
 
 ## Usage
@@ -204,6 +258,12 @@ article-cli init --title "My Presentation" --authors "Author" --type presentatio
 # Initialize with numpex theme (requires theme files from presentation.template.d)
 article-cli init --title "NumPEx Talk" --authors "Author" --type presentation --theme numpex
 
+# Initialize a Typst presentation project
+article-cli init --title "My Typst Talk" --authors "Author" --type typst-presentation
+
+# Initialize a Typst poster project
+article-cli init --title "My Typst Poster" --authors "Author" --type typst-poster
+
 # Specify custom Zotero group ID
 article-cli init --title "My Article" --authors "Author" --group-id 1234567
 
@@ -212,6 +272,13 @@ article-cli init --title "My Article" --authors "Author" --tex-file article.tex
 
 # Force overwrite existing files
 article-cli init --title "My Article" --authors "Author" --force
+
+# Generate CI that checks Zotero bibliography freshness
+article-cli init --title "My Article" --authors "Author" --ci-bib check
+
+# Generate CI with opt-in self-hosted runner discovery
+article-cli init --title "My Article" --authors "Author" \
+  --ci-runner-policy self-hosted-auto --ci-self-hosted-org my-org
 ```
 
 The `init` command sets up:
@@ -225,27 +292,48 @@ The `init` command sets up:
 ### Git Release Management
 
 ```bash
-# Create a new release
-article-cli create v1.2.3
+# Refresh gitinfo2 version metadata
+article-cli version
+
+# Refresh metadata, compile, and check the PDF version text
+article-cli version --compile --check-pdf
+
+# Preview a new release tag
+article-cli release v1 --dry-run
+
+# Create a checked local release tag
+article-cli release v1
+
+# Check bibliography freshness during release, then push the tag
+article-cli release v1 --bib check --push
 
 # List recent releases
 article-cli list --count 10
 
 # Delete a release
 article-cli delete v1.2.3
+
+# Deprecated alias retained for compatibility
+article-cli create v1.2.3
 ```
 
 ### Bibliography Management
 
 ```bash
+# Preview bibliography update
+article-cli bib update --dry-run
+
 # Update bibliography from Zotero
-article-cli update-bibtex
+article-cli bib update
 
 # Specify custom output file
-article-cli update-bibtex --output my-refs.bib
+article-cli bib update --output my-refs.bib
 
 # Skip backup creation
-article-cli update-bibtex --no-backup
+article-cli bib update --no-backup
+
+# Deprecated alias retained for compatibility
+article-cli update-bibtex
 ```
 
 ### LaTeX Compilation
@@ -279,6 +367,32 @@ article-cli compile --clean-first --clean-after
 article-cli compile --output-dir build/
 ```
 
+### Typst Compilation
+
+```bash
+# Compile a Typst document (auto-detects .typ files)
+article-cli compile presentation.typ
+
+# Compile with explicit Typst engine
+article-cli compile --engine typst document.typ
+
+# Watch for changes and auto-recompile
+article-cli compile presentation.typ --watch
+
+# Specify custom font paths
+article-cli compile presentation.typ --font-path fonts/
+
+# Multiple font paths
+article-cli compile presentation.typ --font-path fonts/ --font-path ~/.fonts/
+
+# Specify output directory
+article-cli compile presentation.typ --output-dir build/
+```
+
+**Note:** The engine is automatically detected from the file extension:
+- `.tex` files use LaTeX engines (latexmk by default)
+- `.typ` files use the Typst engine
+
 ### Font Installation
 
 Install fonts for XeLaTeX projects (useful for custom Beamer themes):
@@ -323,9 +437,11 @@ article-cli install-theme my-theme --url https://example.com/theme.zip
 ```
 
 **Available themes:**
-- **numpex**: NumPEx Beamer theme following French government visual identity (requires XeLaTeX and custom fonts)
+- **numpex**: NumPEx theme following French government visual identity
+  - LaTeX: Beamer theme files (requires XeLaTeX and custom fonts)
+  - Typst: `numpex.typ` theme file for Typst presentations
 
-**Complete presentation setup:**
+**Complete LaTeX presentation setup:**
 ```bash
 # 1. Install the theme
 article-cli install-theme numpex
@@ -337,9 +453,27 @@ article-cli install-fonts
 article-cli compile presentation.tex --engine xelatex
 ```
 
+**Complete Typst presentation setup:**
+```bash
+# 1. Install the theme (includes numpex.typ)
+article-cli install-theme numpex
+
+# 2. Compile with Typst
+article-cli compile presentation.typ --font-path fonts/
+```
+
 ### Project Setup
 
 ```bash
+# Diagnose repository readiness without modifying files
+article-cli doctor
+
+# Emit machine-readable diagnostics for CI
+article-cli doctor --json
+
+# Apply safe repairs for hooks, output directories, and gitHeadLocal.gin
+article-cli doctor --fix
+
 # Setup git hooks for gitinfo2
 article-cli setup
 
@@ -351,23 +485,28 @@ article-cli clean
 
 ```bash
 # Override configuration via command line
-article-cli update-bibtex --api-key YOUR_KEY --group-id YOUR_GROUP
+article-cli bib update --api-key YOUR_KEY --group-id YOUR_GROUP
 
 # Specify custom configuration file
-article-cli --config custom-config.toml update-bibtex
+article-cli --config custom-config.toml bib update
 ```
 
-## Version Format
+## Release Tags
+
+The default paper release policy accepts short and full version tags:
+- `vX` for paper milestones (e.g., `v1`)
+- `vX.Y` or `vX.Y.Z` for more detailed paper releases
+- `vX.Y.Z-rc.N`, `vX.Y.Z-beta.N`, or similar pre-release suffixes
 
-Release versions must follow the semantic versioning format:
-- `vX.Y.Z` for stable releases (e.g., `v1.2.3`)
-- `vX.Y.Z-pre.N` for pre-releases (e.g., `v1.2.3-pre.1`)
+Use `[tool.article-cli.release] tag_policy = "semver"` when a repository must require strict `vX.Y.Z` semantic-version tags. The release command does not commit, force-retag, push, or create a GitHub release unless the corresponding explicit flag is passed.
 
 ## Requirements
 
-- Python 3.8+
+- Python 3.9+
 - Git repository with gitinfo2 package (for LaTeX integration)
 - Zotero account with API access (for bibliography features)
+- Typst CLI (for Typst compilation) - install from https://typst.app/
+- Node.js 20+ for building the Antora documentation site
 
 ## License
 
@@ -383,12 +522,31 @@ MIT License - see LICENSE file for details.
 
 ## Changelog
 
-### v1.2.0
-- Add font installation command (`install-fonts`) for XeLaTeX projects
-- Support Marianne and Roboto Mono fonts by default
+### v1.5.0
+- Add `doctor` diagnostics with JSON output and safe `--fix` repairs
+- Split CLI implementation into command modules
+- Make setup hooks more robust and worktree-safe
+- Standardize development and CI workflows on `uv`
+- Add an Antora documentation site using the Feel++ Antora UI
+
+### v1.4.0
+- Add full Typst document compilation support
+- New `TypstCompiler` class for Typst documents
+- Auto-detection of `.typ` files with automatic engine selection
+- Watch mode for Typst with live recompilation
+- Custom font path support (`--font-path` option)
+- New project types: `typst-presentation` and `typst-poster`
+- Theme installation now includes Typst files (e.g., `numpex.typ`)
+- Typst configuration section in config files
+
+### v1.3.0
 - Add theme installation command (`install-theme`) for Beamer presentations
 - Built-in support for numpex theme with automatic download
 - Extended GitHub Actions workflow with XeLaTeX and multi-document support
+
+### v1.2.0
+- Add font installation command (`install-fonts`) for XeLaTeX projects
+- Support Marianne and Roboto Mono fonts by default
 - Add presentation project type with Beamer template support
 - Add `--engine` option for xelatex and lualatex compilation
 - Improved CI/CD with font installation steps
@@ -404,4 +562,4 @@ MIT License - see LICENSE file for details.
 - Git release management
 - Zotero bibliography synchronization
 - LaTeX build file cleanup
-- Configuration file support
+- Configuration file support