Merge pull request #4 from kurtmckee/release-0.2.0

Release 0.2.0

.gitignore

@@ -1,5 +1,6 @@
 /.tox/
 /.pytest_cache/
+/build/
 /dist/
 /venv/
 /.coverage.*

.pre-commit-config.yaml

@@ -41,16 +41,18 @@ repos:
     hooks:
       - id: 'flake8'
         additional_dependencies:
-          - 'flake8-bugbear==23.9.16'
+          - 'flake8-bugbear==23.11.26'
 
   - repo: 'https://github.com/editorconfig-checker/editorconfig-checker.python'
     rev: '2.7.3'
     hooks:
       - id: 'editorconfig-checker'
+        # The README contains YAML that isn't indented using 4 spaces.
+        exclude: 'README.rst'
 
-#  - repo: 'https://github.com/python-jsonschema/check-jsonschema'
-#    rev: '0.27.1'
-#    hooks:
+  - repo: 'https://github.com/python-jsonschema/check-jsonschema'
+    rev: '0.27.2'
+    hooks:
+      - id: 'check-readthedocs'
 #      - id: 'check-dependabot'
 #      - id: 'check-github-workflows'
-#      - id: 'check-readthedocs'

.pre-commit-hooks.yaml

@@ -0,0 +1,11 @@
+- description: 'Check file headers are correct using Chipshot.'
+  id: 'check-headers'
+  name: 'Chipshot - Check headers'
+  entry: 'chipshot'
+  language: 'python'
+
+- description: 'Update file headers, if needed, using Chipshot.'
+  id: 'update-headers'
+  name: 'Chipshot - Update headers'
+  entry: 'chipshot --update'
+  language: 'python'

.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: 'ubuntu-22.04'
+  tools:
+    python: '3.12'
+
+sphinx:
+  configuration: 'docs/conf.py'
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: 'requirements/docs.txt'

CHANGELOG.rst

@@ -23,6 +23,36 @@ Please see the fragment files in the `changelog.d directory`_.
 
 ..  scriv-insert-here
 
+.. _changelog-0.2.0:
+
+0.2.0 - 2023-11-28
+==================
+
+Added
+-----
+
+*   Add two pre-commit hooks: ``check-headers`` and ``update-headers``.
+
+Changed
+-------
+
+*   Allow template literals in the config file using the ``template`` key.
+
+    Paths to template files can be defined in the ``template_path`` key.
+
+*   When no configuration file is specified,
+    ``.chipshot.toml`` will be loaded first (if it exists).
+
+    ``pyproject.toml`` will still be loaded as a fallback
+    if ``.chipshot.toml`` doesn't exist.
+
+*   Rename the ``--debug`` flag to ``--verbose``.
+
+Documentation
+-------------
+
+*   Add initial documentation.
+
 .. _changelog-0.1.0:
 
 0.1.0 - 2023-11-24

README.rst

@@ -26,26 +26,36 @@ but can be configured to support those, too.
 Sample configuration
 ====================
 
-Create a directory that will contain your header template.
-For example, the directory might be named ``assets/headers``.
+Create a file named ``.chipshot.toml`` with the following content:
 
-Then, create a text file that will contain your header template,
-such as ``global.txt``.
-You can use ``{{ year }}`` as a stand-in for the current year.
-
-..  code-block:: text
+..  code-block:: toml
 
-    Copyright 2021-{{ date }} Developer or Company
+    [chipshot]
+    template = """
+    Copyright 2021-{{ year }} Developer or Company
     Released under the terms of the MIT license.
     SPDX-License-Identifier: MIT
+    """
 
-Next, add the following configuration to ``pyproject.toml``:
+You can then run ``chipshot path1 path2`` to see what files will be modified.
+If you're satisfied, run ``chipshot --update path1 path2`` to update the files.
 
-..  code-block:: toml
 
-    [tool.chipshot]
-    template_root = "assets/headers"
-    template = "global.txt"
+Pre-commit hooks
+================
 
-You can then run ``chipshot path1 path2`` to see what files will be modified.
-If you're satisfied, run ``chipshot --update path1 path2`` to update the files.
+Chipshot offers two pre-commit hooks to help you manage your projects:
+
+*   ``check-headers``
+*   ``update-headers``
+
+Here's a sample configuration for ensuring your files have correct headers:
+
+..  code-block:: yaml
+
+    # .pre-commit-config.yaml
+    repos:
+      - repo: 'https://github.com/kurtmckee/chipshot'
+        rev: 'main'
+        hooks:
+          - id: 'update-headers'

TODO.rst

@@ -0,0 +1,14 @@
+*   add CI
+*   write documentation
+*   publish to readthedocs
+*   catch exceptions and report them
+*   allow configuring different headers for different file types.
+    this allows for a license for docs and a license for code
+*   allow file paths (for example, ``scripts/*`` or ``script-without-suffix``)
+*   allow custom encodings
+*   detect encodings using ``.editorconfig``
+*   ignore files using ``.gitignore``
+*   use multiprocessing for faster work
+*   update how similarity is calculated
+    (it doesn't consider all words and reports 100% similarity)
+*   test against major repos

docs/_static/custom.css

@@ -0,0 +1,17 @@
+/*
+ * The CSS code sample comes from:
+ * https://www.a11yproject.com/posts/how-to-hide-content/
+ *
+ * The CSS selector comes from:
+ * https://github.com/pallets/pallets-sphinx-themes/blob/1512b53b/src/pallets_sphinx_themes/themes/pocoo/static/pocoo.css#L486-L498
+ */
+
+.visually-hidden > h1:first-child {
+    clip: rect(0 0 0 0);
+    clip-path: inset(50%);
+    height: 1px;
+    overflow: hidden;
+    position: absolute;
+    white-space: nowrap;
+    width: 1px;
+}

docs/conf.py

@@ -0,0 +1,35 @@
+import pathlib
+import tomllib
+
+# General configuration
+# ---------------------
+
+# The suffix of source filenames.
+source_suffix = ".rst"
+
+# The main toctree document.
+master_doc = "index"
+
+# General information about the project.
+project = "Chipshot"
+copyright = "2022-2023 Kurt McKee"
+
+# Extract the project version.
+pyproject_ = pathlib.Path(__file__).parent.parent / "pyproject.toml"
+info_ = tomllib.loads(pyproject_.read_text())
+version = release = info_["tool"]["poetry"]["version"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+
+# HTML theme configuration
+# ------------------------
+
+html_theme = "alabaster"
+html_static_path = [
+    "_static",
+]
+html_theme_options = {
+    "logo": "logo.png",
+}

docs/index.rst

@@ -0,0 +1,78 @@
+..  rst-class:: visually-hidden
+
+Welcome to the Chipshot documentation
+#####################################
+
+..  image:: _static/banner.png
+    :alt: The Chipshot logo, with a soccer ball shooting up and away from the project name.
+
+Chipshot helps you standardize headers in your source code.
+Its aim is to help ensure that all source files have excellent headers
+with accurate copyright and license information.
+If it can help you achieve your goals, then it will have done its job!
+
+Example
+=======
+
+Chipshot respects byte order marks, newlines, and document prologues
+(like hashbangs and XML declarations) when adding and updating headers.
+Its default configuration supports many different file types
+so it's easy to get started with a minimal configuration file.
+
+..  rubric:: ``.chipshot.toml``
+..  code-block:: toml
+
+    [chipshot]
+    template = """
+    Copyright 2022-{{ year }} Company Name <[email protected]>
+    SPDX-License-Identifier: MIT
+    """
+
+Headers will be rendered as comments based on the file extension.
+
+..  rubric:: Python
+..  code-block:: python
+
+    # Copyright 2022-2023 Company Name <[email protected]>
+    # SPDX-License-Identifier: MIT
+
+..  rubric:: C
+..  code-block:: c
+
+    /*
+     * Copyright 2022-2023 Company Name <[email protected]>
+     * SPDX-License-Identifier: MIT
+     */
+
+
+Getting Started
+===============
+
+..  toctree::
+    :maxdepth: 1
+
+    tutorial/overview
+    tutorial/installing
+    tutorial/configuring
+
+*   Default comment styles gallery
+
+
+How-To Guides
+=============
+
+*   How to customize comment styles
+*   How to integrate Chipshot in your everyday development
+
+
+Reference
+=========
+
+..  toctree::
+    :maxdepth: 1
+
+    reference/boms
+
+*   Configuration file format
+*   Pre-commit hooks
+*   CLI options

docs/reference/boms.rst

@@ -0,0 +1,25 @@
+Byte Order Marks (BOMs)
+#######################
+
+Chipshot initially reads all files as binary.
+If the first bytes correspond to a known byte order mark (BOM),
+Chipshot will decode the file using the encoding scheme indicated by the BOM.
+
+The encoding associated with the BOM is always respected,
+even if Chipshot is configured to expect a different encoding.
+If the file cannot be decoded using the BOM-indicated encoding,
+Chipshot will not try to use any other encoding.
+
+If Chipshot updates the file, the BOM will be retained.
+
+These are the BOMs that Chipshot understands,
+and the associated encoding that will be used if a BOM is encountered.
+
+..  csv-table::
+    :header: "BOM characters", "Encoding"
+
+    "``00 00 fe ff``", "UTF-32 (Big Endian)"
+    "``ff fe 00 00``", "UTF-32 (Little Endian)"
+    "``fe ff``", "UTF-16 (Big Endian)"
+    "``ff fe``", "UTF-16 (Little Endian)"
+    "``ef bb bf``", "UTF-8"