click-docs 0.2.0__tar.gz

click_docs-0.2.0/.changelog-config.yaml

@@ -0,0 +1,133 @@
+# For more configuration information, please see https://coordt.github.io/generate-changelog/
+
+# User variables for reference in other parts of the configuration.
+variables:
+  repo_url: https://github.com/callowayproject/click-docs
+  changelog_filename: CHANGELOG.md
+
+# Pipeline to find the most recent tag for incremental changelog generation.
+# Leave empty to always start at first commit.
+starting_tag_pipeline:
+  - action: ReadFile
+    kwargs:
+      filename: "{{ changelog_filename }}"
+  - action: FirstRegExMatch
+    kwargs:
+      pattern: (?im)^## (?P<rev>\d+\.\d+(?:\.\d+)?)\s+\(\d+-\d{2}-\d{2}\)$
+      named_subgroup: rev
+
+# Used as the version title of the changes since the last valid tag.
+unreleased_label: Unreleased
+
+# Process the commit's first line for use in the changelog.
+summary_pipeline:
+  - action: strip_spaces
+  - action: Strip
+    comment: Get rid of any periods so we don't get double periods
+    kwargs:
+      chars: .
+  - action: SetDefault
+    args:
+      - no commit message
+  - action: capitalize
+  - action: append_dot
+
+# Process the commit's body for use in the changelog.
+body_pipeline:
+  - action: ParseTrailers
+    comment: Parse the trailers into metadata.
+    kwargs:
+      commit_metadata: save_commit_metadata
+
+# Process and store the full or partial changelog.
+output_pipeline:
+  - action: IncrementalFileInsert
+    kwargs:
+      filename: "{{ changelog_filename }}"
+      last_heading_pattern: (?im)^## \d+\.\d+(?:\.\d+)?\s+\([0-9]+-[0-9]{2}-[0-9]{2}\)$
+  - action: MDFormat
+    kwargs:
+      filename: CHANGELOG.md
+
+# Full or relative paths to look for output generation templates.
+template_dirs:
+  - ".github/changelog_templates/"
+
+# Group the commits within a version by these commit attributes.
+group_by:
+  - metadata.category
+
+# Only tags matching this regular expression are used for the changelog.
+tag_pattern: ^[0-9]+\.[0-9]+(?:\.[0-9]+)?$
+
+# Tells ``git-log`` whether to include merge commits in the log.
+include_merges: false
+
+# Ignore commits whose summary line matches any of these regular expression patterns.
+ignore_patterns:
+  - '[@!]minor'
+  - '[@!]cosmetic'
+  - '[@!]refactor'
+  - '[@!]wip'
+  - ^$
+  - ^Merge branch
+  - ^Merge pull
+  - ^Version updated
+
+# Set the commit's category metadata to the first classifier that returns ``True``.
+commit_classifiers:
+  - action: SummaryRegexMatch
+    category: New
+    kwargs:
+      pattern: (?i)^(?:new|add)[^\n]*$
+  - action: SummaryRegexMatch
+    category: Updates
+    kwargs:
+      pattern: (?i)^(?:update|change|rename|remove|delete|improve|refactor|chg|modif)[^\n]*$
+  - action: SummaryRegexMatch
+    category: Fixes
+    kwargs:
+      pattern: (?i)^(?:fix)[^\n]*$
+  - action:
+    category: Other
+
+# Tokens in git commit trailers that indicate authorship.
+valid_author_tokens:
+  - author
+  - based-on-a-patch-by
+  - based-on-patch-by
+  - co-authored-by
+  - co-committed-by
+  - contributions-by
+  - from
+  - helped-by
+  - improved-by
+  - original-patch-by
+
+# Rules applied to commits to determine the type of release to suggest.
+release_hint_rules:
+  - match_result: dev
+    branch: ^((?!master|main).)*$
+  - match_result: patch
+    path: pyproject.toml
+    branch: master|main
+  - match_result: patch
+    grouping: Other
+    path: click_docs/*
+    branch: master|main
+  - match_result: patch
+    grouping: Fixes
+    path: click_docs/*
+    branch: master|main
+  - match_result: minor
+    grouping: Updates
+    path: click_docs/*
+    branch: master|main
+  - match_result: minor
+    grouping: New
+    path: click_docs/*
+    branch: master|main
+  - match_result: major
+    grouping: Breaking Changes
+    path: click_docs/*
+    branch: master|main

click_docs-0.2.0/.claude/agents/docstring-reviewer.md

@@ -0,0 +1,24 @@
+---
+name: docstring-reviewer
+description: Review Python files for docstring quality, Google-style compliance, and interrogate coverage
+---
+
+You are a Python docstring specialist for the click-docs project, which enforces:
+- Google-style docstrings (pydoclint)
+- 90% docstring coverage (interrogate)
+- Type annotation consistency (ruff ANN rules)
+
+When given Python files to review:
+
+1. Check every public function, class, and method has a Google-style docstring with appropriate sections (Args, Returns, Raises)
+2. Flag any missing docstrings that would cause interrogate coverage to fall below 90%
+3. Verify arg descriptions match the function signature (pydoclint compliance)
+4. Check that Returns section is present when the function returns a non-None value
+5. Check that Raises section is present for any explicitly raised exceptions
+
+Output a structured list of violations with:
+- File path and line number
+- Violation type (missing docstring / missing Args / missing Returns / missing Raises / style error)
+- Suggested fix (provide the corrected docstring)
+
+Focus only on docstring issues. Do not report other code quality issues.

click_docs-0.2.0/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "file=\"$CLAUDE_TOOL_INPUT_FILE_PATH\"; if echo \"$file\" | grep -q '\\.py$'; then uv run ruff format \"$file\" 2>/dev/null; uv run ruff check --fix \"$file\" 2>/dev/null; true; fi"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if echo \"$CLAUDE_TOOL_INPUT_FILE_PATH\" | grep -q 'uv\\.lock'; then echo 'Blocked: uv.lock must not be edited directly. Use uv add/remove instead.' >&2; exit 2; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

click_docs-0.2.0/.claude/settings.local.json

@@ -0,0 +1,27 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git config:*)",
+      "Bash(wc:*)",
+      "Bash(grep -r \"TODO\\\\|FIXME\\\\|XXX\\\\|HACK\\\\|BUG\" /Users/coordt/code/click-docs --include=*.py --include=*.md)",
+      "Bash(gh repo:*)",
+      "Bash(git:*)",
+      "Bash(uv run:*)",
+      "Bash(claude mcp:*)",
+      "Bash(.venv/bin/python -m pytest tests/test_generator.py::TestHeaderDepth tests/test_generator.py::TestStyleTable tests/test_cli.py::TestCliFormattingOptions -x --no-header -q)",
+      "Bash(.venv/bin/python -m pytest tests/test_generator.py::TestHeaderDepth tests/test_generator.py::TestStyleTable tests/test_cli.py::TestCliFormattingOptions --no-header -q)",
+      "Bash(.venv/bin/python -c \"\nimport sys; sys.path.insert\\(0, '.'\\)\nfrom tests.test_generator import special_types_cmd\nfrom click_docs.generator import generate_docs\n\ntable = generate_docs\\(special_types_cmd, program_name='special-types', style='table'\\)\nplain = generate_docs\\(special_types_cmd, program_name='special-types', style='plain'\\)\nprint\\('=== TABLE ==='\\)\nprint\\(repr\\(table\\)\\)\nprint\\('=== PLAIN ==='\\)\nprint\\(repr\\(plain\\)\\)\n\")",
+      "Bash(.venv/bin/python -m pytest tests/ --no-header -q)",
+      "Bash(find /Users/coordt/code/click-docs -type d -not -path */.* -not -path */__pycache__* -not -path *.egg-info*)",
+      "Bash(python -m pytest tests/test_generator.py::TestGenerateDocs tests/test_generator.py::TestHeaderDepth tests/test_generator.py::TestStyleTable tests/test_cli.py -x -q)",
+      "Bash(xxd tests/app/expected_special_types_table.md)",
+      "Bash(xxd tests/app/expected_special_types_plain.md)",
+      "Bash(xxd tests/app/expected_hello.md)",
+      "Bash(xxd tests/app/expected_cli.md)",
+      "Bash(python3:*)"
+    ]
+  },
+  "disabledMcpjsonServers": [
+    "github"
+  ]
+}

click_docs-0.2.0/.claude/skills/release/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: release
+description: Cut a release by bumping version, generating changelog, committing, and tagging
+disable-model-invocation: true
+---
+
+Run the release process for click-docs:
+
+1. Ask the user what version bump type they want: `patch`, `minor`, or `major` (if not provided as args)
+2. Run `uv run bump-my-version bump {{args}}` to bump the version
+3. Run `uv run generate-changelog` to update CHANGELOG.md
+4. Show the user the resulting diff with `git diff`
+5. Ask the user to confirm before proceeding
+6. Stage and commit: `git add CHANGELOG.md click_docs/__init__.py && git commit -m "Version updated from ... to ..."`
+7. Push with tags: `git push && git push --tags`
+8. Remind the user the GitHub Actions release workflow will now trigger

click_docs-0.2.0/.editorconfig

@@ -0,0 +1,23 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{py,rst,ini}]
+indent_style = space
+indent_size = 4
+
+[*.{html,css,scss,json,yml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = true
+
+[Makefile]
+indent_style = tab

click_docs-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,33 @@
+name: Bug Report
+description: File a bug report.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you do, what happened, and what did you expect?
+      placeholder: Tell us what you see!
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: What version of our software are you running?
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      description: What operating system are you using?
+      options:
+        - Linux
+        - MacOS
+        - Windows

click_docs-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,26 @@
+name: Feature Request
+description: Suggest an idea for this project
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Is your feature request related to a problem? Please describe.
+      description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+  - type: textarea
+    id: request
+    attributes:
+      label: Describe the solution you'd like.
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: considered-alternatives
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Add any other context or screenshots about the feature request here.

click_docs-0.2.0/.github/changelog_templates/commit.md.jinja

@@ -0,0 +1,9 @@
+- {{ commit.summary }} [{{ commit.short_sha }}]({{ repo_url }}/commit/{{ commit.sha }})
+  {{ commit.body|indent(2, first=True) }}
+  {% for key, val in commit.metadata["trailers"].items() %}
+  {% if key not in VALID_AUTHOR_TOKENS %}
+  **{{ key }}:** {{ val|join(", ") }}
+
+  {% endif %}
+
+{% endfor %}

click_docs-0.2.0/.github/changelog_templates/version_heading.md.jinja

@@ -0,0 +1,4 @@
+## {{ version.label }} ({{ version.date_time.strftime("%Y-%m-%d") }})
+{% if version.previous_tag %}
+[Compare the full difference.]({{ repo_url }}/compare/{{ version.previous_tag }}...{{ version.tag }})
+{% endif %}

click_docs-0.2.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+# Keep GitHub Actions up to date with GitHub's Dependabot...
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    groups:
+      github-actions:
+        patterns:
+          - "*"  # Group all Actions updates into a single larger pull request
+    schedule:
+      interval: weekly
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

click_docs-0.2.0/.github/workflows/build-python.yaml

@@ -0,0 +1,72 @@
+name: Build Python Package
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: The branch, tag or SHA to checkout. Otherwise, uses the default branch.
+        required: false
+        type: string
+        default: ""
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: The branch, tag or SHA to checkout. Otherwise, uses the default branch.
+        required: false
+        type: string
+        default: ""
+
+jobs:
+  build-package:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.ref }}
+      - name: Package
+        uses: hynek/build-and-inspect-python-package@v2
+
+  call-release-github:
+    needs: build-package
+    permissions:
+      contents: write
+      packages: write
+      id-token: write
+    uses: ./.github/workflows/release-github.yaml
+    with:
+      ref: ${{ inputs.ref }}
+
+#  call-release-container:
+#    needs: build-package
+#    permissions:
+#      contents: write
+#      packages: write
+#      id-token: write
+#    uses: ./.github/workflows/release-container.yaml
+#    with:
+#      ref: ${{ inputs.ref }}
+
+
+  release-pypi:
+    needs: build-package
+    permissions:
+      contents: read
+      id-token: write
+    name: Publish released package to pypi.org
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download packages built by build-and-inspect-python-package
+        uses: actions/download-artifact@v8
+        with:
+          name: Packages
+          path: dist
+
+      - name: Upload package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+  

click_docs-0.2.0/.github/workflows/bump-version-preview.yaml

@@ -0,0 +1,77 @@
+name: Display version hint
+
+on:
+  pull_request:
+    types: [synchronize, opened, reopened, ready_for_review]
+    branches: [master, main]
+
+permissions:
+  contents: read
+  pull-requests: write
+  id-token: write
+
+concurrency: version-preview-${{ github.ref }}
+
+jobs:
+  preview-version:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Setup Git
+        uses: fregante/setup-git-user@v2
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Install requirements
+        run: |
+          python -m pip install bump-my-version
+
+      - name: Get the release hint
+        id: changelog
+        uses: docker://ghcr.io/callowayproject/generate-changelog:v0
+        with:
+          branch_override: ${{ github.event.pull_request.base.ref }}
+
+      - name: Get Metadata
+        id: get-metadata
+        run: |
+          PR_NUMBER=$(gh pr view --json number -q .number || echo "${{ github.event.number }}")
+          REVISION=$(git describe --tags --long | awk -F- '{print $2}')
+          echo "RELEASE_KIND=${{ steps.changelog.outputs.release_hint }}" >> $GITHUB_ENV
+          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+          echo "REVISION=$REVISION" >> $GITHUB_ENV
+
+      - name: Bump version dry run
+        if: ${{ env.RELEASE_KIND != 'no-release' }}
+        shell: bash
+        run: |
+          # This will display a full log of what would happen if we were to bump the version.
+          bump-my-version bump --dry-run --verbose "$RELEASE_KIND"
+
+          # This retrieves the current and new version numbers as a JSON-formatted string.
+          VERSION_INFO=$(bump-my-version show --format json --increment "$RELEASE_KIND" current_version new_version)
+          echo "CURRENT_VERSION=$(echo $VERSION_INFO | jq -r .current_version)" >> $GITHUB_ENV
+          echo "NEW_VERSION=$(echo $VERSION_INFO | jq -r .new_version)" >> $GITHUB_ENV
+
+      - name: Set no-release information
+        if: ${{ env.RELEASE_KIND == 'no-release' }}
+        run: |
+          echo "CURRENT_VERSION=$(bump-my-version show current_version)" >> $GITHUB_ENV
+          echo "NEW_VERSION=$(bump-my-version show current_version)" >> $GITHUB_ENV
+
+      - name: Display the version hint
+        uses: s-gehring/singleton-comment@v1
+        with:
+          comment-body: |
+            **Version hint:** ${{ env.RELEASE_KIND }}
+            **Current version:** ${{ env.CURRENT_VERSION }}
+            **New version (when merged):** ${{ env.NEW_VERSION }}

click_docs-0.2.0/.github/workflows/bump-version.yaml

@@ -0,0 +1,77 @@
+name: Bump the version on merge
+on:
+  pull_request:
+    types: [closed]
+    branches: [master, main]
+
+jobs:
+  bump-version:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.merged == true
+    permissions:
+      contents: write
+      id-token: write
+    outputs:
+      build_package: ${{ steps.bump-version.outputs.build_package }}
+      tag_name: ${{ steps.bump-version.outputs.tag_name }}
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Setup Git
+        uses: fregante/setup-git-user@v2
+
+      - name: Install requirements
+        run: |
+          python -m pip install bump-my-version
+
+      - name: Generate changelog and release hint
+        id: changelog
+        uses: docker://ghcr.io/callowayproject/generate-changelog:v0
+
+      - name: Bump version
+        id: bump-version
+        shell: bash
+        run: |
+          PR_NUMBER=$(gh pr view --json number -q .number || echo "")
+          REVISION=$(git describe --tags --long | awk -F- '{print $2}')
+          RELEASE_KIND=${{ steps.changelog.outputs.release_hint }}
+          export PR_NUMBER REVISION RELEASE_KIND
+          case "$RELEASE_KIND" in
+            major|minor|patch)
+              bump-my-version bump --allow-dirty --verbose "$RELEASE_KIND"
+              git push
+              git push --tags
+              echo "tag_name=$(bump-my-version show current_version)" >> $GITHUB_OUTPUT
+              echo "build_package=true" >> $GITHUB_OUTPUT
+              ;;
+            *)
+              echo "build_package=false" >> $GITHUB_OUTPUT
+              ;;
+          esac
+        env:
+            GH_TOKEN: ${{ github.token }}
+
+  call-build-python:
+    needs: bump-version
+    if: ${{ needs.bump-version.outputs.build_package == 'true' }}
+    permissions:
+      contents: write
+      attestations: write
+      id-token: write
+      packages: write
+    uses: ./.github/workflows/build-python.yaml
+    with:
+      ref: ${{ needs.bump-version.outputs.tag_name }}

click_docs-0.2.0/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,72 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ master, main ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ master, main ]
+  schedule:
+    - cron: '37 21 * * 5'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v6
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v4
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+
+    #   If the Autobuild fails above, remove it and uncomment the following three lines.
+    #   modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.
+
+    # - run: |
+    #   echo "Run, Build Application using script"
+    #   ./location_of_script_within_repo/buildscript.sh
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4