From 98c6ad57e1f1f8576e8102af073ea717dade6ee1 Mon Sep 17 00:00:00 2001 From: Jakob Gamper <97gamjak@gmail.com> Date: Sun, 13 Sep 2026 13:53:32 +0000 Subject: [PATCH] docs: fill in user guide overview and configuration reference Adds the two pages the docs/sections placeholder was waiting for: - Overview: feature areas (C++ checks, license headers, changelog management, git tag utilities) and a full CLI command reference with examples for all 8 console scripts. - Configuration File: complete devops.toml/.devops.toml reference, section by section and key by key, with types, defaults, discovery rules, and the CHANGELOG.md insertion-marker format it depends on. All details verified directly against src/devops/config/*.py and src/devops/scripts/*.py rather than taken from memory. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_0126spNDGtqDKMoYtuPT7JfW --- CHANGELOG.md | 6 + docs/source/sections/configuration.rst | 272 +++++++++++++++++++++++++ docs/source/sections/index.rst | 7 +- docs/source/sections/overview.rst | 186 +++++++++++++++++ 4 files changed, 468 insertions(+), 3 deletions(-) create mode 100644 docs/source/sections/configuration.rst create mode 100644 docs/source/sections/overview.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index fa4333a..871ec37 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file. ## Next Release +### Features + +#### Documentation + +- Fill in the user guide with an "Overview" page (feature areas and full CLI command reference) and a "Configuration File" page documenting every `devops.toml`/`.devops.toml` section and key, discovery rules, and the changelog insertion-marker format + ## [0.1.4](https://github.com/repo/owner/releases/tag/0.1.4) - 2026-09-13 diff --git a/docs/source/sections/configuration.rst b/docs/source/sections/configuration.rst new file mode 100644 index 0000000..080078b --- /dev/null +++ b/docs/source/sections/configuration.rst @@ -0,0 +1,272 @@ +Configuration File +=================== + +Every ``devops`` command reads its defaults from a single TOML configuration +file. This page is the complete reference for that file: where it's +discovered, every section and key it supports, and the exact defaults used +when a key (or the whole file) is missing. + +Discovery +--------- + +On startup, ``devops`` looks in the **current working directory** for: + +#. ``devops.toml`` +#. ``.devops.toml`` + +- If exactly **one** of these files exists, it is loaded and parsed. +- If **neither** exists, the built-in defaults documented below are used. +- If **both** exist, a warning is logged and the built-in defaults are used + — the ambiguity is intentionally not resolved automatically. + +There is no parent-directory search: the file must sit in the directory the +command is run from. + +Generating a starting point +---------------------------- + +Rather than writing the file by hand, run: + +.. code-block:: console + + generate_toml_template + +This writes ``devops.toml.template`` in the current directory containing +every key below, commented out, set to its default value. Rename it to +``devops.toml`` (or ``.devops.toml``) and uncomment/edit what you need to +override. + +Reference +--------- + +Keys are optional unless stated otherwise — anything omitted falls back to +its default. + +``[exclude]`` +^^^^^^^^^^^^^ + +Controls which files are excluded from checks. + +.. list-table:: + :header-rows: 1 + :widths: 20 15 15 50 + + * - Key + - Type + - Default + - Description + * - ``buggy_cpp_macros`` + - list of strings + - ``[]`` + - Macro names that mark a file as affected by a known compiler bug. + :ref:`filter_buggy_cpp_files ` excludes + any file that calls one of these macros (matched as a whole word + immediately followed by ``(``). + +.. code-block:: toml + + [exclude] + buggy_cpp_macros = ["MACRO_A", "MACRO_B"] + +``[logging]`` +^^^^^^^^^^^^^ + +Per-subsystem log levels. Valid values: ``NONE``, ``DEBUG``, ``INFO``, +``WARNING``, ``ERROR``, ``CRITICAL``. + +.. list-table:: + :header-rows: 1 + :widths: 20 15 15 50 + + * - Key + - Type + - Default + - Description + * - ``global_level`` + - string + - ``"INFO"`` + - Root logger level. + * - ``utils_level`` + - string + - ``"INFO"`` + - Level for the ``utils`` subsystem. + * - ``config_level`` + - string + - ``"INFO"`` + - Level for the configuration-loading subsystem itself. + * - ``cpp_level`` + - string + - ``"INFO"`` + - Level for the C++ checks subsystem. + +.. code-block:: toml + + [logging] + global_level = "INFO" + cpp_level = "DEBUG" + +``[git]`` +^^^^^^^^^ + +Controls how Git tags are parsed by +:ref:`get_latest_tag ` and +:ref:`increase_latest_tag `. + +.. list-table:: + :header-rows: 1 + :widths: 20 15 15 50 + + * - Key + - Type + - Default + - Description + * - ``tag_prefix`` + - string + - ``""`` + - Prefix expected before the ``major.minor.patch`` part of a tag (for + example ``"v"`` for tags like ``v1.2.3``). Tags without this prefix + are ignored when finding the latest tag. + * - ``empty_tag_list_allowed`` + - boolean + - ``true`` + - If ``true`` and no matching tags exist, the latest tag is treated as + ``0.0.0`` instead of raising an error. + +.. code-block:: toml + + [git] + tag_prefix = "v" + empty_tag_list_allowed = true + +``[cpp]`` +^^^^^^^^^ + +Controls the checks run by :ref:`cpp_checks `. + +.. list-table:: + :header-rows: 1 + :widths: 20 15 15 50 + + * - Key + - Type + - Default + - Description + * - ``style_checks`` + - boolean + - ``true`` + - Enable header guard presence checks and keyword-order checks (e.g. + ``static inline constexpr``). + * - ``license_header_check`` + - boolean + - ``true`` + - Enable verifying that files start with the configured license + header. Has no effect if ``license_header`` is not set. + * - ``license_header`` + - string or unset + - unset + - Path to a file whose contents must appear at the top of every C++ + source/header file. Required for ``license_header_check`` to do + anything. + * - ``check_only_staged_files`` + - boolean + - ``false`` + - Restrict checks to files currently staged in Git (for pre-commit + hook usage). + * - ``header_guards_according_to_filepath`` + - boolean + - ``false`` + - Additionally require the header guard macro name to match a name + derived from the file's path, not just be present. + +.. code-block:: toml + + [cpp] + style_checks = true + license_header_check = true + license_header = "LICENSE_HEADER.txt" + check_only_staged_files = false + header_guards_according_to_filepath = true + +``[file]`` +^^^^^^^^^^ + +Controls changelog file handling and text encoding. + +.. list-table:: + :header-rows: 1 + :widths: 20 15 15 50 + + * - Key + - Type + - Default + - Description + * - ``encoding`` + - string + - ``"utf-8"`` + - Encoding used to read/write changelog files. Must be a valid Python + codec name; an invalid value fails config loading immediately. + * - ``changelog_paths`` + - string or list of strings + - ``["CHANGELOG.md"]`` + - The changelog file(s) managed by + :ref:`update_changelogs `. A single string is + accepted and treated as a one-element list. + * - ``default_changelog_path`` + - string or unset + - first entry of ``changelog_paths`` + - Which changelog :ref:`update_changelog ` writes + to when ``--changelog-path`` isn't given on the command line. + +.. code-block:: toml + + [file] + encoding = "utf-8" + changelog_paths = ["CHANGELOG.md"] + default_changelog_path = "CHANGELOG.md" + +Full example +------------ + +.. code-block:: toml + + [exclude] + buggy_cpp_macros = ["OLD_COMPILER_WORKAROUND"] + + [logging] + global_level = "INFO" + cpp_level = "DEBUG" + + [git] + tag_prefix = "v" + empty_tag_list_allowed = true + + [cpp] + style_checks = true + license_header_check = true + license_header = "LICENSE_HEADER.txt" + header_guards_according_to_filepath = true + + [file] + encoding = "utf-8" + changelog_paths = ["CHANGELOG.md"] + +Changelog file format +---------------------- + +The ``[file]`` section governs *which* changelog files are managed, but the +changelog itself has one structural requirement: +:ref:`update_changelog ` and +:ref:`update_changelogs ` need a ``## Next Release`` +heading followed by an ```` comment. A new entry is +inserted directly below the heading and above the marker on every run: + +.. code-block:: markdown + + # Changelog + + ## Next Release + + + ## [0.1.4](https://github.com/OWNER/REPO/releases/tag/0.1.4) - 2026-09-13 + + ... diff --git a/docs/source/sections/index.rst b/docs/source/sections/index.rst index 07e7e67..7b19b59 100644 --- a/docs/source/sections/index.rst +++ b/docs/source/sections/index.rst @@ -1,7 +1,8 @@ User Guide ========== -.. note:: +.. toctree:: + :maxdepth: 2 - This section is a placeholder. Explanatory guide pages (installation, - configuration, usage walkthroughs, ...) will be added here. + overview + configuration diff --git a/docs/source/sections/overview.rst b/docs/source/sections/overview.rst new file mode 100644 index 0000000..62a36e5 --- /dev/null +++ b/docs/source/sections/overview.rst @@ -0,0 +1,186 @@ +Overview +======== + +``devops`` is a collection of small, focused command line tools used to keep +C++ projects consistent: style and license checks on C++ sources, changelog +maintenance, and Git tag/version helpers. All tools read shared settings from +a single :doc:`configuration file ` (``devops.toml`` or +``.devops.toml``), so behavior can be tuned once and reused across every +command and CI job. + +Feature areas +------------- + +C++ code quality checks +^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``cpp`` subsystem builds a set of rules from the ``[cpp]`` configuration +and runs them against a project's C++ sources: + +- **Header guards** — every ``.h``, ``.hpp``, ``.tpp`` and ``.impl.hpp`` file + must contain a proper ``#ifndef`` / ``#define`` / ``#endif`` guard. If + ``header_guards_according_to_filepath`` is enabled, the guard macro name is + also checked against a name derived from the file's path. +- **Key sequence order** — flags keyword sequences such as + ``static inline constexpr`` that are written out of the expected order. +- **License headers** — verifies that source and header files start with the + contents of a configured license header file (see below). + +Run it with :ref:`cpp_checks `. + +License header management +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Beyond just checking for a license header, ``devops`` can insert one into +files that are missing it, one file at a time or recursively across +directories. See :ref:`add_license_header ` and +:ref:`add_license_headers `. + +Buggy file filtering +^^^^^^^^^^^^^^^^^^^^^ + +Some C++ codebases need to work around known compiler bugs tied to specific +macros. :ref:`filter_buggy_cpp_files ` scans a +directory tree and prints only the files that do *not* use any macro listed +under ``exclude.buggy_cpp_macros`` — useful for scoping a workaround or a +build flag to the files that actually need it. + +Changelog management +^^^^^^^^^^^^^^^^^^^^^ + +``devops`` maintains ``CHANGELOG.md`` files with a simple insertion-marker +convention: a ``## Next Release`` heading followed by an +```` comment. Running +:ref:`update_changelog ` inserts a new +``## [VERSION](.../releases/tag/VERSION) - YYYY-MM-DD`` entry right above the +marker and moves the marker down, ready for the next release. +:ref:`update_changelogs ` applies the same update to +every path configured under ``file.changelog_paths`` at once, which is how +this project keeps multiple changelogs (if any) in sync from a single CI +step. + +Git tag utilities +^^^^^^^^^^^^^^^^^^ + +:ref:`get_latest_tag ` and +:ref:`increase_latest_tag ` parse Git tags as +``..`` and let CI compute the next release +version without hand-maintaining it — this is what this project's own +release workflow uses to bump versions on ``hotfix/*`` branches. + +CLI command reference +---------------------- + +All commands are installed as console scripts and read defaults from the +:doc:`configuration file ` unless overridden on the command +line. + +.. _cli-cpp_checks: + +``cpp_checks`` +^^^^^^^^^^^^^^ + +Run the configured C++ style, header guard, and license header checks. +Exits with status ``1`` if any check fails. + +.. code-block:: console + + cpp_checks --dirs src include + cpp_checks --license-header LICENSE_HEADER.txt + +.. _cli-add_license_header: + +``add_license_header`` +^^^^^^^^^^^^^^^^^^^^^^^ + +Prepend a license header to a single file if it doesn't already have one. + +.. code-block:: console + + add_license_header src/main.cpp LICENSE_HEADER.txt + add_license_header src/main.cpp LICENSE_HEADER.txt --dry-run + +.. _cli-add_license_headers: + +``add_license_headers`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Prepend a license header to every C++ file found under the given +directories (current directory if omitted). + +.. code-block:: console + + add_license_headers LICENSE_HEADER.txt --dirs src include + +.. _cli-filter_buggy_cpp_files: + +``filter_buggy_cpp_files`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Print the C++ files under the given directories that do **not** contain any +macro listed in ``exclude.buggy_cpp_macros``. + +.. code-block:: console + + filter_buggy_cpp_files --dirs src include + +.. _cli-update_changelog: + +``update_changelog`` +^^^^^^^^^^^^^^^^^^^^^ + +Insert a new version entry into one changelog file. + +.. code-block:: console + + update_changelog 1.2.0 + update_changelog 1.2.0 --changelog-path docs/CHANGELOG.md + +.. _cli-update_changelogs: + +``update_changelogs`` +^^^^^^^^^^^^^^^^^^^^^^ + +Insert a new version entry into every changelog configured under +``file.changelog_paths`` (or a custom set passed explicitly). + +.. code-block:: console + + update_changelogs 1.2.0 + update_changelogs 1.2.0 --changelog-paths CHANGELOG.md docs/CHANGELOG.md + +.. _cli-get_latest_tag: + +``get_latest_tag`` +^^^^^^^^^^^^^^^^^^^ + +Print the latest Git tag, parsed as ``..``. + +.. code-block:: console + + get_latest_tag + get_latest_tag --prefix v + +.. _cli-increase_latest_tag: + +``increase_latest_tag`` +^^^^^^^^^^^^^^^^^^^^^^^^ + +Print the next version after bumping the latest Git tag. Exactly one of +``--major``, ``--minor``, or ``--patch`` must be given. + +.. code-block:: console + + increase_latest_tag --patch + increase_latest_tag --major --prefix v + +``generate_toml_template`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Write ``devops.toml.template`` to the current directory: every configuration +key, commented out, set to its default value. See +:doc:`configuration` for what each key does. + +.. code-block:: console + + generate_toml_template