Skip to content

Commit 2dc7f72

Browse files
jonathansickjonathansick
authored
Merge pull request #1 from jsickcodes/initial-version
Initial version
2 parents 9c2d2e5 + a41d69a commit 2dc7f72

19 files changed

Lines changed: 464 additions & 2 deletions

‎.github/workflows/ci.yaml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: CI
2+
3+
"on": ["pull_request", "push"]
4+
5+
jobs:
6+
pre-commit:
7+
runs-on: ubuntu-latest
8+
steps:
9+
- uses: actions/checkout@v2
10+
with:
11+
fetch-depth: 0
12+
13+
- uses: actions/setup-python@v2
14+
15+
- uses: pre-commit/action@v2.0.0
16+
17+
typing:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@v2
21+
with:
22+
fetch-depth: 0 # full history for setuptools_scm
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v2
26+
with:
27+
python-version: 3.8
28+
29+
- name: Python install
30+
run: |
31+
python -m pip install --upgrade pip
32+
pip install tox
33+
34+
- name: Run mypy
35+
run: tox -e typing
36+
37+
test:
38+
runs-on: ubuntu-latest
39+
40+
strategy:
41+
matrix:
42+
python-version:
43+
- 3.7
44+
- 3.8
45+
- 3.9
46+
47+
steps:
48+
- uses: actions/checkout@v2
49+
with:
50+
fetch-depth: 0 # full history for setuptools_scm
51+
52+
- name: Set up Python
53+
uses: actions/setup-python@v2
54+
55+
with:
56+
python-version: ${{ matrix.python-version }}
57+
58+
- name: Python install
59+
run: |
60+
python -m pip install --upgrade pip
61+
pip install tox
62+
63+
- name: Run tox
64+
run: tox -e py,packaging

‎.pre-commit-config.yaml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
repos:
2+
- repo: https://github.com/pre-commit/pre-commit-hooks
3+
rev: v3.4.0
4+
hooks:
5+
- id: check-yaml
6+
- id: check-toml
7+
- id: check-json
8+
- id: trailing-whitespace
9+
10+
- repo: https://github.com/Lucas-C/pre-commit-hooks-markup
11+
rev: v1.0.1
12+
hooks:
13+
- id: rst-linter
14+
files: (README\.rst)|(CHANGELOG\.rst)
15+
16+
- repo: https://github.com/PyCQA/isort
17+
rev: 5.7.0
18+
hooks:
19+
- id: isort
20+
additional_dependencies:
21+
- toml
22+
23+
- repo: https://github.com/psf/black
24+
rev: 20.8b1
25+
hooks:
26+
- id: black
27+
28+
- repo: https://github.com/asottile/blacken-docs
29+
rev: v1.10.0
30+
hooks:
31+
- id: blacken-docs
32+
additional_dependencies: [black==20.8b1]
33+
args: [-l, "79", -t, py38]
34+
35+
- repo: https://gitlab.com/pycqa/flake8
36+
rev: 3.9.0
37+
hooks:
38+
- id: flake8

‎.pre-commit-hooks.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
- id: docxplain
2+
name: Docx plain text mirror
3+
description: Mirror an Office (docx) document in plain text.
4+
entry: docxplain
5+
language: python
6+
files: "\\.docx$"

‎CHANGELOG.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Change log
2+
==========
3+
4+
Unreleased
5+
----------
6+
7+
Initial release.

‎README.md‎

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎README.rst‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
#####################
2+
pre-commit-docx-plain
3+
#####################
4+
5+
**Pre-commit hook for mirroring Word (docx) files into plain text files (using Pandoc).**
6+
7+
This pre-commit hook provides a solution for organizations that manage Word (.docx) documents with Git and GitHub.
8+
With this hook, whenever a Word document is committed or updated in a Git repository, a plain text version is also created.
9+
You can use this plain-text mirror to facilitate GitHub Pull Request reviews.
10+
11+
Set up
12+
======
13+
14+
At the root of your document's Git repository, add a file named ``.pre-commit-config.yaml`` with the following contents::
15+
16+
repos:
17+
- repo: https://github.com/jsickcodes/pre-commit-docx-plain
18+
rev: 0.1.0
19+
hooks:
20+
- id: docxplain
21+
22+
Next, you'll need to install pre-commit (if you haven't already)::
23+
24+
pip install -U pre-commit
25+
26+
Initialize the pre-commit hooks in the repository itself::
27+
28+
pre-commit install
29+
30+
If the repository has an existing Word document, it is a good idea to create the mirrored plain text file now::
31+
32+
pre-commit run --all-files
33+
34+
Commit the plain text (``.txt``) file that is generated.
35+
36+
Local usage
37+
===========
38+
39+
If you are contributing to a repository using ``pre-commit-docx-plain``, you will also need to install pre-commit itself and install the pre-commit hooks in your local clone of the repository::
40+
41+
pre-commit install -U pre-commit
42+
pre-commit install
43+
44+
Now, when you update and commit changes to the Word file in your repository, pre-commit will run the ``pre-commit-docx-plain`` hook and generate a new or updated mirror of the file in plain text.
45+
Use ``git add`` to stage the plain text file and try your ``git commit`` again.
46+
On this second try, the plain text mirror file should be in sync with the Word file, and the commit can go ahead.
47+
48+
Usage with GitHub Actions
49+
=========================
50+
51+
You can run ``pre-commit-docx-plain`` in GitHub Actions to ensure that the plain-text mirror file is always up-to-date.
52+
If the repository does not already have a GitHub Actions workflow, create a file with the path ``.github/workflows/ci.yaml`` with the following contents::
53+
54+
name: CI
55+
56+
"on": [push, pull_request]
57+
58+
jobs:
59+
pre-commit:
60+
runs-on: ubuntu-latest
61+
62+
steps:
63+
- uses: actions/checkout@v2
64+
65+
- name: Set up Python
66+
uses: actions/setup-python@v2
67+
68+
- name: Run pre-commit hooks
69+
uses: pre-commit/action@v2.0.0
70+
71+
This workflow will generate a build "failure" if the plain-text mirror file is out of date with the Word file in the repository — as might happen if a contributor did not install pre-commit locally.
72+
73+
Automatically generate the plain text mirror from GitHub Actions
74+
================================================================
75+
76+
To avoid complexities related to installing pre-commit, the GitHub Actions workflow can be configured to automatically generate, commit, and push updates to the plain text mirror.
77+
The ``.github/workflows/ci.yaml`` file::
78+
79+
name: CI
80+
81+
"on": [push, pull_request]
82+
83+
jobs:
84+
pre-commit:
85+
runs-on: ubuntu-latest
86+
87+
steps:
88+
- uses: actions/checkout@v2
89+
with:
90+
fetch-depth: 0
91+
92+
- name: Set up Python
93+
uses: actions/setup-python@v2
94+
95+
- name: Run pre-commit hooks
96+
uses: pre-commit/action@v2.0.0
97+
with:
98+
token: ${{ secrets.GITHUB_TOKEN }}
99+
100+
Note that this workflow can only run with private repositories.
101+
The ``GITHUB_TOKEN`` secret is not available to public forks.
102+
103+
When using this workflow, contributors need to either pull down the plain text file update to their local branch, or be prepared to use a forced push (``git push --force``) because their branch is "behind" the GitHub origin.

‎pyproject.toml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
[build-system]
2+
requires = [
3+
"setuptools>=42",
4+
"wheel",
5+
"setuptools_scm[toml]>=3.4"
6+
]
7+
build-backend = 'setuptools.build_meta'
8+
9+
[tool.setuptools_scm]
10+
11+
[tool.black]
12+
line-length = 79
13+
target-version = ['py38']
14+
exclude = '''
15+
/(
16+
\.eggs
17+
| \.git
18+
| \.mypy_cache
19+
| \.tox
20+
| \.venv
21+
| _build
22+
| build
23+
| dist
24+
)/
25+
'''
26+
# Use single-quoted strings so TOML treats the string like a Python r-string
27+
# Multi-line strings are implicitly treated by black as regular expressions
28+
29+
[tool.isort]
30+
include_trailing_comma = true
31+
multi_line_output = 3
32+
known_first_party = "docxplain"
33+
skip = ["docs/conf.py"]

‎setup.cfg‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
[metadata]
2+
name = docxplain
3+
description = Convert Office (docx) files to plain text using pandoc.
4+
author = Jonathan Sick
5+
author_email = hi@jsick.codes
6+
long_description = file: README.rst, CHANGELOG.rst, LICENSE
7+
long_description_content_type = text/x-rst
8+
url = https://github.com/jsickcodes/pre-commit-docx-plain
9+
project_urls =
10+
Change log = https://github.com/jsickcodes/pre-commit-docx-plain/blob/master/CHANGELOG.rst
11+
Source code = https://github.com/jsickcodes/pre-commit-docx-plain
12+
Issue tracker = https://github.com/jsickcodes/pre-commit-docx-plain/issues
13+
classifiers =
14+
Development Status :: 4 - Beta
15+
License :: OSI Approved :: MIT License
16+
Programming Language :: Python
17+
Programming Language :: Python :: 3
18+
Intended Audience :: Developers
19+
Natural Language :: English
20+
Operating System :: POSIX
21+
keywords =
22+
precommit
23+
24+
[options]
25+
zip_safe = False
26+
include_package_data = True
27+
package_dir =
28+
= src
29+
packages = find:
30+
python_requires = >=3.7
31+
setup_requires =
32+
setuptools_scm
33+
install_requires =
34+
importlib_metadata; python_version < "3.8"
35+
pypandoc
36+
py-pandoc
37+
38+
[options.packages.find]
39+
where = src
40+
41+
[options.entry_points]
42+
console_scripts =
43+
docxplain = docxplain.cli:main
44+
45+
[options.extras_require]
46+
dev =
47+
pytest
48+
49+
[flake8]
50+
max-line-length = 79
51+
# E203: whitespace before :, flake8 disagrees with PEP 8
52+
# W503: line break after binary operator, flake8 disagrees with PEP 8
53+
ignore = E203, W503
54+
55+
[mypy]
56+
disallow_untyped_defs = True
57+
disallow_incomplete_defs = True
58+
ignore_missing_imports = True
59+
show_error_codes = True
60+
strict_equality = True
61+
warn_redundant_casts = True
62+
warn_unreachable = True
63+
warn_unused_ignores = True

‎setup.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
from setuptools import setup
2+
3+
setup(use_scm_version=True)

‎src/docxplain/__init__.py‎

Whitespace-only changes.

0 commit comments

Comments
 (0)