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

{article_cli-1.4.0 → 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.4.0 → article_cli-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: article-cli
-Version: 1.4.0
+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
@@ -35,21 +35,26 @@ 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
 
@@ -71,17 +76,19 @@ A command-line tool for managing LaTeX and Typst documents with git integration
 - **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
@@ -89,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
@@ -117,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!
@@ -127,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
    ```
 
@@ -138,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
@@ -166,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"]
 
@@ -224,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:
@@ -237,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
@@ -389,6 +465,15 @@ 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
 
@@ -400,24 +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
 
@@ -433,6 +522,13 @@ MIT License - see LICENSE file for details.
 
 ## Changelog
 
+### 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
@@ -466,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

{article_cli-1.4.0 → article_cli-2.0.0}/README.md

@@ -16,17 +16,19 @@ A command-line tool for managing LaTeX and Typst documents with git integration
 - **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
@@ -34,9 +36,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
@@ -62,8 +87,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!
@@ -72,6 +101,8 @@ pip install -e .
 
 1. **Setup git hooks** (run once per repository):
    ```bash
+   article-cli doctor
+   article-cli doctor --fix
    article-cli setup
    ```
 
@@ -83,12 +114,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
@@ -111,9 +145,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"]
 
@@ -169,6 +212,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:
@@ -182,27 +232,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
@@ -334,6 +405,15 @@ 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
 
@@ -345,24 +425,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
 
@@ -378,6 +462,13 @@ MIT License - see LICENSE file for details.
 
 ## Changelog
 
+### 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
@@ -411,4 +502,4 @@ MIT License - see LICENSE file for details.
 - Git release management
 - Zotero bibliography synchronization
 - LaTeX build file cleanup
-- Configuration file support
+- Configuration file support

{article_cli-1.4.0 → article_cli-2.0.0}/pyproject.toml

@@ -4,40 +4,57 @@ build-backend = "hatchling.build"
 
 [project]
 name = "article-cli"
-version = "1.4.0"
+version = "2.0.0"
 authors = [
     {name = "Christophe Prud'homme", email = "prudhomm@cemosis.fr"},
 ]
 description = "CLI tool for managing LaTeX and Typst documents with git integration and Zotero bibliography"
 readme = "README.md"
 license = {file = "LICENSE"}
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering",
     "Topic :: Text Processing :: Markup :: LaTeX",
 ]
 keywords = ["latex", "typst", "git", "zotero", "bibliography", "academic", "research", "presentations"]
 dependencies = [
     "requests>=2.28.0",
+    "PyYAML>=6.0",
+    "Jinja2>=3.1",
+    "tomli>=2.0.0; python_version < '3.11'",
 ]
 
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",
     "pytest-cov",
-    "black>=23.0",
+    "black==25.11.0",
     "flake8>=6.0",
-    "mypy>=1.0",
+    "mypy>=1.0,<2.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+    "types-requests",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "black==25.11.0",
+    "flake8>=6.0",
+    "mypy>=1.0,<2.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
     "types-requests",
 ]
 
@@ -63,7 +80,7 @@ include = [
 
 [tool.black]
 line-length = 88
-target-version = ['py38']
+target-version = ['py39']
 include = '\.pyi?$'
 extend-exclude = '''
 /(
@@ -101,6 +118,7 @@ ignore_missing_imports = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["src"]
 python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
@@ -108,4 +126,4 @@ addopts = [
     "--strict-markers",
     "--strict-config",
     "--verbose",
-]
+]

{article_cli-1.4.0 → article_cli-2.0.0}/src/article_cli/__init__.py

@@ -9,7 +9,7 @@ This package provides tools for:
 - Git hooks setup
 """
 
-__version__ = "1.4.0"
+__version__ = "1.5.0"
 __author__ = "Christophe Prud'homme"
 __email__ = "prudhomm@cemosis.fr"