diff --git a/.cspell.json b/.cspell.json index e25af51..052a617 100644 --- a/.cspell.json +++ b/.cspell.json @@ -4,18 +4,25 @@ "words": [ "arjndr", "attrbox", + "Autobuild", "begert", + "codeql", "docopt", "isinstance", "isrange", "lukasbindreiter", "Metaist", + "mypy", "pdfmerge", "pdfs", "pdoc", + "pypa", "pypdf", + "pypi", "pyproject", + "pyright", "rangify", + "setuptools", "unrotated", "venv" ] diff --git a/.gitignore b/.gitignore index e3ca062..0b3e0b6 100644 --- a/.gitignore +++ b/.gitignore @@ -17,7 +17,7 @@ _seed.py __pycache__ # test -.coverage* +.coverage .mypy_cache .pytest_cache .ruff_cache diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f2578f..2db268e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,30 +1,89 @@ -## Setting up a dev environment +# Contributing + +## Local Development ```bash -git clone +# get the code +git clone git@github.com:metaist/pdfmerge.git cd pdfmerge -python -m .venv --prompt pdfmerge -source .venv/bin/activate -pip install -e ".[dev]" +# create a virtual environment +python -m venv .venv --prompt pdfmerge +. .venv/bin/activate +pip install --upgrade pip + +# install dependencies and dev tools +pip install -e ".[dev]" pnpm install -g cspell ``` -## Making a release +As you work on the code, you should periodically run: + +```bash +pdm lint # for type checks +pdm test # for unit tests +``` + +This repo generally tries to maintain type-correctness (via `mypy` and `pyright`) and complete unit test coverage. + +## Making a Release + +Checkout `prod`: ```bash git checkout prod git merge --no-ff --no-edit main -# update __init__.py version -# update changelog.md -pdm all +``` + +Update top-most `__init__.py`: + +```python +__version__ = "X.0.1" +``` + +Update `CHANGELOG.md`: + +Sections order is: `Fixed`, `Changed`, `Added`, `Deprecated`, `Removed`, `Security`. + +```markdown +--- -git commit -m "release: $VER" -git tag "$VER" +[X.0.1]: https://github.com/metaist/pdfmerge/compare/X.0.0...X.0.1 + +## [X.0.1] - XXXX-XX-XXT00:00:00Z + +**Fixed** + +**Changed** + +**Added** + +**Deprecated** + +**Removed** + +**Security** +``` + +### + +```bash +export VER="X.0.1" + +# update docs +pdm docs + +# check build +pip install -e . + +# commit and push tags +git commit -am "release: $VER" +git tag $VER git push git push --tags - git checkout main git merge --no-ff --no-edit prod git push ``` + +[Create the release on GitHub](https://github.com/metaist/pdfmerge/releases/new). The `pypi.yaml` workflow will attempt to publish it to PyPI. diff --git a/README.md b/README.md index cfb3d43..b07a6f4 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,14 @@ -# pdfmerge - -_Command-line utility for merging, splicing, and rotating PDF documents._ - -[![Build Status](https://img.shields.io/github/actions/workflow/status/metaist/pdfmerge/.github/workflows/ci.yaml?branch=main&style=for-the-badge)](https://github.com/metaist/pdfmerge/actions) -[![pdfmerge on PyPI](https://img.shields.io/pypi/v/pdfmerge.svg?color=blue&style=for-the-badge)](https://pypi.org/project/pdfmerge) -[![Supported Python versions](https://img.shields.io/pypi/pyversions/pdfmerge?style=for-the-badge)](https://pypi.org/project/pdfmerge) - -[Changelog] - [Issues] - [Documentation] - -[changelog]: https://github.com/metaist/pdfmerge/blob/main/CHANGELOG.md -[issues]: https://github.com/metaist/pdfmerge/issues -[documentation]: https://metaist.github.io/pdfmerge/ +# pdfmerge: CLI for merging, splicing, and rotating PDFs + +

+ pdfmerge
+ Staple the Squirrel +

+

+ Build + PyPI + Supported Python Versions +

## Why? @@ -24,7 +22,10 @@ python -m pip install pdfmerge ## Usage - $ pdfmerge [-h] [--version] [-o FILE|--output FILE] [-p PASSWORD|--password PASSWORD] PATH[RULE[, RULE ...]] [PATH[RULE, ...]] ...] + $ pdfmerge [-h] [--version] + [-o FILE|--output FILE] + [-p PASSWORD|--password PASSWORD] + PATH[RULE[, RULE ...]] [[PATH[RULE, ...]] ...] - `-o`, `--output` output file (default: `output.pdf`). - `-p`, '--password` password for encrypted files (default: empty string). @@ -45,7 +46,7 @@ python -m pip install pdfmerge This example illustrates several features: -- specifying an output file (must not be any of the input files) +- specifying an output file - merging multiple files, some more than once - splicing parts of file using indices (1-based; negatives allowed) - including the same page multiple times @@ -65,14 +66,4 @@ pdfmerge(["pdf-1.pdf", "pdf-2.pdf[2>]"], "output.pdf") ## License -[MIT License](https://github.com/metaist/pypdf/blob/main/LICENSE.md) - -[ci-image]: https://travis-ci.org/metaist/pdfmerge.png?branch=master -[ci-status]: http://travis-ci.org/metaist/pdfmerge -[gh-code]: https://github.com/metaist/pdfmerge/zipball/master -[gh-issues]: https://github.com/metaist/pdfmerge/issues -[gh-issues-all]: https://github.com/metaist/pdfmerge/issues/search?q= -[gh-pdfmerge]: https://github.com/metaist/pdfmerge/blob/master/pdfmerge.py -[gh-setup]: https://github.com/metaist/pdfmerge/blob/master/releases/pdfmerge-latest-setup.exe -[osi-mit]: http://opensource.org/licenses/MIT -[pypdf]: https://pypi.python.org/pypi/pyPdf +[MIT License](https://github.com/metaist/pdfmerge/blob/main/LICENSE.md) diff --git a/docs/index.html b/docs/index.html index 09942b7..36c6ae1 100644 --- a/docs/index.html +++ b/docs/index.html @@ -23,17 +23,25 @@

Package pdfmerge

Command-line utility for merging, splicing, and rotating PDF documents.

-

Build Status -pdfmerge on PyPI -Supported Python versions

-

Changelog - Issues - Documentation

+

+pdfmerge
+Staple the Squirrel +

+

+Build +PyPI +Supported Python Versions +

Why?

I find myself merging bits of different PDFs fairly regularly and really wanted a simple CLI way to do it.

Install

python -m pip install pdfmerge

Usage

-
$ pdfmerge [-h] [--version] [-o FILE|--output FILE] [-p PASSWORD|--password PASSWORD] PATH[RULE[, RULE ...]] [PATH[RULE, ...]] ...]
+
$ pdfmerge [-h] [--version]
+  [-o FILE|--output FILE]
+  [-p PASSWORD|--password PASSWORD]
+  PATH[RULE[, RULE ...]] [[PATH[RULE, ...]] ...]
 

 
    
 
  • -o, --output output file (default: output.pdf).
    • 
@@ -54,7 +62,7 @@ 
    Command-line Example

This example illustrates several features: