latex-toolbox 0.1.0__tar.gz

latex_toolbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Gourmelen
+
+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.

latex_toolbox-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: latex-toolbox
+Version: 0.1.0
+Summary: CLI for creating standalone LaTeX projects from this toolbox.
+License-Expression: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Dynamic: license-file

latex_toolbox-0.1.0/README.md

@@ -0,0 +1,443 @@
+# LaTeX Toolbox
+
+[Read this in French](./README.fr.md)
+
+LaTeX Toolbox is a local toolkit for creating polished, reusable, standalone LaTeX projects from ready-made templates.
+
+It is built for a simple workflow:
+- keep your templates, styles, and shared assets in this repository;
+- generate a new project with the `latex-toolbox` command;
+- work on the generated project in VS Code;
+- version each generated project in its own Git repository if needed.
+
+If you regularly write course reports, research papers, TER reports, or collaborative LaTeX documents, this repository gives you a clean starting point every time without rebuilding your structure from scratch.
+
+## What the toolbox does
+
+When you create a project, the toolbox:
+- copies the selected template;
+- renames the main `.tex` file to match the project name;
+- copies the required LaTeX styles into the project;
+- copies the logos from `assets/logos/`;
+- creates a project-level `.gitignore` for common LaTeX build files;
+- creates a project that can compile on its own.
+
+Generated projects do not depend on this repository at compile time.
+
+## Requirements
+
+Recommended setup:
+- Python 3
+- a LaTeX distribution such as `MacTeX`
+- VS Code
+- the `LaTeX Workshop` extension
+
+Useful VS Code extensions:
+- `LaTeX Workshop`
+- `LTeX+`
+- `Code Spell Checker`
+
+Important:
+- if you use `LaTeX Workshop`, disable `vscode-pdf` to avoid PDF viewer conflicts.
+
+## Install the command
+
+The easiest installation method is `pipx`.
+
+From this repository root:
+
+```bash
+cd /path/to/latex-toolbox
+brew install pipx
+pipx install --editable .
+```
+
+After that, the command is available as:
+
+```bash
+latex-toolbox
+```
+
+If the command is not found after installation:
+
+```bash
+pipx ensurepath
+```
+
+Then open a new terminal window.
+
+## Quick start
+
+Create a project report in the current directory:
+
+```bash
+latex-toolbox create --name signal-processing-report --template rapport-projet-en
+```
+
+Create a research-style paper:
+
+```bash
+latex-toolbox create --name audio-search-paper --template research
+```
+
+Then open the generated folder in VS Code and start editing the main file:
+
+```text
+./signal-processing-report/signal-processing-report.tex
+```
+
+## Available commands
+
+List templates:
+
+```bash
+latex-toolbox list-templates
+```
+
+Check or bootstrap a machine for LaTeX work:
+
+```bash
+latex-toolbox setup
+latex-toolbox setup --check-only
+latex-toolbox setup --install-tex
+```
+
+Supported automatic installation paths:
+- macOS: `brew`
+- Ubuntu / Debian: `apt-get`
+- Fedora: `dnf`
+- Arch Linux: `pacman`
+- Windows: `winget`
+
+Create a project:
+
+```bash
+latex-toolbox create --name my-project --template rapport-projet-en
+```
+
+Rules:
+- `--name` is required
+- `--template` is required
+- the project is created in the current directory
+- the created folder uses the project name
+
+Example:
+
+```bash
+cd ~/Desktop
+latex-toolbox create --name shazam-report --template research
+```
+
+This creates:
+
+```text
+~/Desktop/shazam-report/
+```
+
+Rename a generated project:
+
+```bash
+latex-toolbox rename shazam-report shazam-final-report
+```
+
+This renames:
+- the project folder
+- the main `.tex` file
+- the main build artifacts when they already exist
+
+You can also run the command from inside the project folder itself:
+
+```bash
+cd shazam-report
+latex-toolbox rename shazam-final-report
+```
+
+## Recommended workflow
+
+### 1. Create a project
+
+```bash
+latex-toolbox create --name my-project --template rapport-projet-en
+```
+
+Real examples:
+
+```bash
+latex-toolbox create --name deep-learning-lab --template rapport-projet-en
+latex-toolbox create --name rapport-analyse-signaux --template rapport-projet-fr
+latex-toolbox create --name keyword-spotting-paper --template research
+```
+
+### 2. Open the project in VS Code
+
+Open the main file, for example:
+
+```text
+./my-project/my-project.tex
+```
+
+### 3. Fill in the metadata
+
+Cover-page information is centralized in:
+
+```text
+frontmatter/metadata.tex
+```
+
+Typical values include:
+- report title
+- course name
+- authors
+- supervisors
+- project links
+- university logo
+
+Example:
+
+```tex
+\newcommand{\reporttitle}{Audio Fingerprinting Study}
+\newcommand{\coursename}{Machine Learning}
+
+\resetauthors
+\addauthor{Alice Martin}{}
+\addauthor{Bob Durand}{}
+
+\resetteachers
+\addteacher{Dr Example}{}
+
+\resetprojectlinks
+\addprojectlink{Repository}{https://github.com/example/audio-fingerprinting}
+```
+
+If you leave the second argument empty in `\addauthor{...}{}` or `\addteacher{...}{}`, no role is displayed.
+
+### 4. Compile in VS Code
+
+With `LaTeX Workshop`:
+- open the main `.tex` file;
+- run `LaTeX Workshop: View LaTeX PDF`;
+- save the file to rebuild;
+- the PDF refreshes after each successful compilation.
+
+### 5. Version the generated project
+
+Each generated project is standalone, so you can version it separately:
+
+```bash
+cd my-project
+git init
+git add .
+git commit -m "Initial report"
+```
+
+Then create a dedicated GitHub repository for that project only.
+
+Typical collaboration workflow:
+- create the project with `latex-toolbox`;
+- initialize Git inside the generated folder;
+- create one private GitHub repository for that project;
+- invite only the people who should access that document.
+
+## Available templates
+
+### `rapport-projet-en`
+
+English project-report template with:
+- cover page
+- table of contents
+- introduction
+- conclusion
+- AI statement
+
+### `rapport-projet-fr`
+
+Same structure as `rapport-projet-en`, but in French.
+
+### `rapport-ter`
+
+English TER-style report template with a more detailed academic structure.
+
+### `research`
+
+English research-style template with:
+- cover page
+- abstract
+- table of contents
+- two-column main body
+- introduction
+- conclusion
+- appendix
+- AI usage note
+- BibTeX bibliography
+
+## Generated project structure
+
+Typical structure:
+
+```text
+my-project/
+├── my-project.tex
+├── frontmatter/
+├── sections/
+├── backmatter/ or appendix/
+├── references/ or bibliography/
+├── figures/
+├── images/
+├── screens/
+├── assets/
+│   ├── images/common/
+│   └── logos/
+└── styles/packages/
+```
+
+Important points:
+- the main file uses the project name;
+- LaTeX styles are copied into the project;
+- logos are copied into the project;
+- the project can be shared without shipping the whole toolbox repository.
+
+## Modular styles
+
+The source styles live in:
+
+```text
+styles/packages/
+```
+
+Main files:
+- `university-project-report.sty`
+- `university-ter-report.sty`
+- `research-article.sty`
+- `report-metadata.sty`
+- `report-tables.sty`
+- `report-code-python.sty`
+- `report-code-bash.sty`
+- `report-colors.sty`
+- `report-ter-titlepage.sty`
+- `report-theorems-fr.sty`
+
+When a project is created, these styles are copied into the generated project under:
+
+```text
+styles/packages/
+```
+
+## Assets and logos
+
+The repository-level folder:
+
+```text
+assets/logos/
+```
+
+is used as the source for logos copied into new projects.
+
+In a generated project:
+- place logos in `assets/logos/`
+- place reusable images in `assets/images/common/`
+
+## Bibliography
+
+The `research` template uses a separate BibTeX file.
+
+Typical path:
+
+```text
+references/references.bib
+```
+
+Add your references there and compile the document normally.
+
+## VS Code snippets
+
+Snippets are provided in:
+
+```text
+.vscode/latex.code-snippets
+```
+
+Useful snippet prefixes:
+- `ltx-code-py`
+- `ltx-code-sh`
+- `ltx-fig`
+- `ltx-screen`
+- `ltx-ai`
+- `ltx-toc`
+
+## Evolving the toolbox
+
+If you update:
+- templates in `templates/`
+- styles in `styles/packages/`
+- logos in `assets/logos/`
+
+then future generated projects will include those changes.
+
+Already-generated projects are not updated automatically, because they embed their own local copies.
+
+## Repository structure
+
+```text
+LaTeX/
+├── assets/
+├── latex_toolbox/
+├── projects/
+├── scripts/
+├── styles/
+├── templates/
+└── .vscode/
+```
+
+Role of each folder:
+- `latex_toolbox/`: Python code for the CLI
+- `templates/`: source templates
+- `styles/`: shared toolbox styles
+- `assets/`: shared logos and reusable resources
+- `projects/`: optional place to keep real generated projects
+- `scripts/`: compatibility wrappers
+
+## Quick command reference
+
+List templates:
+
+```bash
+latex-toolbox list-templates
+```
+
+Rename a project:
+
+```bash
+latex-toolbox rename old-project-name new-project-name
+```
+
+Check the local machine setup:
+
+```bash
+latex-toolbox setup --check-only
+```
+
+Create an English project report:
+
+```bash
+latex-toolbox create --name my-project --template rapport-projet-en
+```
+
+Create a French project report:
+
+```bash
+latex-toolbox create --name mon-projet --template rapport-projet-fr
+```
+
+Create a research project:
+
+```bash
+latex-toolbox create --name paper-audio-search --template research
+```
+
+## Summary
+
+LaTeX Toolbox helps you:
+- create LaTeX projects quickly;
+- reuse your styles and logos;
+- work comfortably in VS Code;
+- share each generated project as its own Git repository.

latex_toolbox-0.1.0/latex_toolbox/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+  "recommendations": [
+    "James-Yu.latex-workshop",
+    "ltex-plus.vscode-ltex-plus",
+    "streetsidesoftware.code-spell-checker",
+    "streetsidesoftware.code-spell-checker-french",
+    "MS-vsliveshare.vsliveshare"
+  ]
+}

latex_toolbox-0.1.0/latex_toolbox/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

latex_toolbox-0.1.0/latex_toolbox/assets/images/common/README.md

@@ -0,0 +1,8 @@
+Place ici les PNG, JPG ou PDF que tu reutilises dans plusieurs projets.
+
+Exemples :
+
+- schemas generiques
+- captures d'ecran recurrentes
+- signatures visuelles
+- icones maison

latex_toolbox-0.1.0/latex_toolbox/assets/logos/README.md

@@ -0,0 +1,8 @@
+Place ici les logos reutilises entre plusieurs documents.
+
+Exemples :
+
+- logo labo
+- logo entreprise
+- logo universite
+- logo-up-maths-info.jpg pour le template TER IAD/VMI

latex_toolbox-0.1.0/latex_toolbox/cli.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .project import (
+    available_templates,
+    create_project,
+    rename_current_project,
+    rename_project,
+)
+from .setup import run_setup
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="latex-toolbox",
+        description="Utilities for generating standalone LaTeX projects from the toolbox.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    create_parser = subparsers.add_parser(
+        "create",
+        help="Create a new LaTeX project from a template.",
+    )
+    create_parser.add_argument(
+        "--name",
+        required=True,
+        help="Name of the report and of the generated main .tex file.",
+    )
+    create_parser.add_argument(
+        "--template",
+        required=True,
+        help="Template name to use.",
+    )
+
+    rename_parser = subparsers.add_parser(
+        "rename",
+        help="Rename a generated LaTeX project folder and its main .tex file.",
+    )
+    rename_parser.add_argument(
+        "names",
+        nargs="+",
+        help="Use `old_name new_name` from the parent folder, or only `new_name` from inside the project folder.",
+    )
+
+    setup_parser = subparsers.add_parser(
+        "setup",
+        help="Install VS Code extensions when possible and check LaTeX prerequisites.",
+    )
+    setup_parser.add_argument(
+        "--check-only",
+        action="store_true",
+        help="Only check the current environment without installing VS Code extensions.",
+    )
+    setup_parser.add_argument(
+        "--skip-extensions",
+        action="store_true",
+        help="Skip VS Code extension installation.",
+    )
+    setup_parser.add_argument(
+        "--install-tex",
+        action="store_true",
+        help="Try to install a LaTeX distribution with a common package manager for the current OS.",
+    )
+
+    subparsers.add_parser(
+        "list-templates",
+        help="List the available templates.",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "list-templates":
+        for template_name in available_templates():
+            print(template_name)
+        return 0
+
+    if args.command == "create":
+        try:
+            target_dir, main_tex_file = create_project(
+                name=args.name,
+                template=args.template,
+            )
+        except (ValueError, FileExistsError) as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+
+        print(f"Project created in: {target_dir}")
+        print(f"Open next: {main_tex_file}")
+        print("The project now embeds its local styles in styles/packages/.")
+        print(f"Template used: {args.template}")
+        print(f"Current parent folder: {target_dir.parent}")
+        print("Remember to customise frontmatter/metadata.tex and the sections.")
+        return 0
+
+    if args.command == "rename":
+        try:
+            if len(args.names) == 1:
+                target_dir, main_tex_file = rename_current_project(
+                    new_name=args.names[0],
+                )
+            elif len(args.names) == 2:
+                target_dir, main_tex_file = rename_project(
+                    old_name=args.names[0],
+                    new_name=args.names[1],
+                )
+            else:
+                print(
+                    "Usage: latex-toolbox rename <new-name> "
+                    "or latex-toolbox rename <old-name> <new-name>",
+                    file=sys.stderr,
+                )
+                return 1
+        except (FileNotFoundError, FileExistsError) as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+
+        print(f"Project renamed in: {target_dir}")
+        print(f"New main file: {main_tex_file}")
+        print("The project folder and the main .tex file have been renamed.")
+        print("Build files tied to the main name were also renamed when they existed.")
+        return 0
+
+    if args.command == "setup":
+        return run_setup(
+            check_only=args.check_only,
+            skip_extensions=args.skip_extensions,
+            install_tex=args.install_tex,
+        )
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())