Refresh linters & formatters (#269)

Author: jsh9

.pre-commit-config.yaml

@@ -1,45 +1,86 @@
 ---
 exclude: ^tests/test_data/
 repos:
-  - repo: https://github.com/pycqa/isort
-    rev: 6.0.1
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
     hooks:
-      - id: isort
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+        exclude: \.json$|\.ipynb$
+      - id: requirements-txt-fixer
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: check-toml
+      - id: check-yaml
+      - id: name-tests-test
+        args: [--pytest-test-first]
+        exclude: ^tests/helpers\.py$
+      - id: check-merge-conflict
   - repo: https://github.com/jsh9/muff-pre-commit
-    rev: 0.12.11.1
+    rev: 0.13.2
     hooks:
       - id: muff-format
         args: [--config, muff.toml]
   - repo: https://github.com/lyz-code/yamlfix
-    rev: 1.17.0
+    rev: 1.18.0
     hooks:
       - id: yamlfix
+  - repo: https://github.com/pappasam/toml-sort
+    rev: v0.24.3
+    hooks:
+      - id: toml-sort-fix
+        args:
+          - --in-place
+          - --sort-table-keys
+          - --sort-inline-tables
+          - --sort-first=name,version,dependencies,requires-python,authors,maintainers
+          - --trailing-comma-inline-array
+          - --sort-inline-arrays
+  - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
+    rev: v2.15.0
+    hooks:
+      - id: pretty-format-ini
+        args: [--autofix]
   - repo: https://github.com/hukkin/mdformat
-    rev: 0.7.22  # Use the ref you want to point at
+    rev: 1.0.0
     hooks:
       - id: mdformat
-        args: [--wrap, '79']
-        additional_dependencies: [mdformat-tables]
-  - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v6.0.0
+        args: [--wrap=79, --number]
+        additional_dependencies: [mdformat-gfm]
+  - repo: https://github.com/jsh9/format-json
+    rev: 0.1.2
     hooks:
-      - id: end-of-file-fixer
-      - id: trailing-whitespace
-      - id: pretty-format-json
-        args: [--no-ensure-ascii, --indent=4, --no-sort-keys]
-  - repo: https://github.com/pre-commit/pre-commit
-    rev: v4.3.0
+      - id: format-json
+        args:
+          - --autofix
+          - --no-ensure-ascii
+          - --indent=4
+          - --no-sort-keys
+          - --no-eof-newline
+  - repo: https://github.com/jsh9/markdown-heading-numbering
+    rev: 0.1.0
     hooks:
-      - id: validate_manifest
+      - id: markdown-heading-numbering
+        exclude: ^CHANGELOG\.md$
   - repo: https://github.com/jsh9/markdown-toc-creator
-    rev: 0.0.10
+    rev: 0.1.1
     hooks:
       - id: markdown-toc-creator
+        exclude: ^AGENTS\.md$|^CHANGELOG\.md$
+  - repo: https://github.com/jsh9/format-docstring
+    rev: 0.2.3
+    hooks:
+      - id: format-docstring
+        name: Format docstrings in .py files
+        args: [--line-length=79]
+      - id: format-docstring-jupyter
+        name: Format docstrings in .ipynb files
+        args: [--line-length=79]
   - repo: https://github.com/jsh9/blank-line-after-blocks
     rev: 0.1.4
     hooks:
       - id: blank-line-after-blocks
-        args: [--exclude, r"tests/|_generated\.py$"]
+        args: [--exclude, r"tests/test_data|_generated\.py$"]
   - repo: local
     hooks:
       - id: copy_readme

.pre_commit_helper_scripts/copy_readme.py

@@ -1,4 +1,4 @@
-"""Copy `README.md` into `docs/index.md` at every pre-commit runs"""
+"""Copy ``README.md`` into ``docs/index.md`` at every pre-commit runs"""
 
 with open('README.md', encoding='UTF-8') as fp:
     lines = fp.readlines()

AGENTS.md

@@ -3,32 +3,32 @@
 This file provides guidance to AI coding assistants when working with code in
 this repository.
 
-## pydoclint Project Conventions
+## 1. pydoclint Project Conventions
 
-### Code Style
+### 1.1. Code Style
 
 - Use camelCase for function and variable names (not snake_case)
 
-### Branch Naming
+### 1.2. Branch Naming
 
 - Format: `yyyy-mm-dd-What-this-branch-does`
 
-### Commit Messages & PR Titles
+### 1.3. Commit Messages & PR Titles
 
 - Use action verbs (imperative mood), not past tense
 - Good: "Add feature", "Fix bug"
 - Bad: "Added feature", "Fixed bug"
 
-## Development Commands
+## 2. Development Commands
 
-### Testing
+### 2.1. Testing
 
 - `pytest --tb=long .` - Run all tests with detailed traceback
 - `tox` - Run full test suite across multiple Python versions
 - `tox -e py311` - Run tests on specific Python version (py39, py310, py311,
   py312, py313)
 
-### Code Quality
+### 2.2. Code Quality
 
 - `mypy pydoclint/` - Type checking
 - `muff format --diff --config=muff.toml pydoclint tests` - Format checking
@@ -37,7 +37,7 @@ this repository.
 - `pydoclint --config=pyproject.toml .` - Self-check using pydoclint
 - `pre-commit run -a` - Run all pre-commit hooks
 
-### Specialized Tox Commands
+### 2.3. Specialized Tox Commands
 
 - `tox -e mypy` - Type checking only
 - `tox -e muff` - Format checking only
@@ -47,7 +47,7 @@ this repository.
 - `tox -e flake8-docstrings` - Docstring style checks
 - `tox -e pre-commit` - Pre-commit hooks (skips muff formatter)
 
-### Running a Single Test
+### 2.4. Running a Single Test
 
 Use pytest with specific test file or test function:
 
@@ -56,12 +56,12 @@ pytest tests/test_main.py
 pytest tests/test_main.py::test_function_name
 ```
 
-## Architecture Overview
+## 3. Architecture Overview
 
 Pydoclint is a Python docstring linter that checks docstring sections against
 function signatures. The core architecture consists of:
 
-### Main Components
+### 3.1. Main Components
 
 - **main.py**: CLI entry point using Click, handles command-line options and
   orchestrates linting
@@ -72,7 +72,7 @@ function signatures. The core architecture consists of:
   sources
 - **baseline.py**: Baseline functionality for gradual adoption
 
-### Utils Package Structure
+### 3.2. Utils Package Structure
 
 - **arg.py/argList.py**: Function argument representation and handling
 - **doc.py**: Docstring parsing and representation
@@ -86,21 +86,21 @@ function signatures. The core architecture consists of:
   function bodies
 - **visitor_helper.py**: Helper functions for the main visitor
 
-### Supported Docstring Styles
+### 3.3. Supported Docstring Styles
 
 - **Numpy**: numpydoc format
 - **Google**: Google-style docstrings
 - **Sphinx**: Sphinx/reStructuredText format
 
-### Key Features
+### 3.4. Key Features
 
 - Fast AST-based analysis (thousands of times faster than darglint)
 - Supports type hint checking against docstring parameter types
 - Class attribute documentation checking
 - Baseline mode for gradual adoption in existing codebases
 - Both standalone CLI and flake8 plugin modes
 
-### Test Structure
+### 3.5. Test Structure
 
 - `tests/data/` contains test cases organized by docstring style (google,
   numpy, sphinx, edge_cases)

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Change Log
 
+## [0.7.6] - 2025-10-26
+
+- Changed
+  - Updated linter and auto-formatter configurations
+  - Made a lot of changes to fix code style; some logic was also updated per
+    the suggestions of linters
+- Full diff
+  - https://github.com/jsh9/pydoclint/compare/0.7.5...0.7.6
+
 ## [0.7.5] - 2025-10-25
 
 - Fixed
@@ -467,7 +476,7 @@
   - Added baseline file integration and 2 options:
     1. `--generate-baseline True` Generate baseline content, and write it to a
        file specified from `--baseline` option path.
-    1. `--baseline <PATH>` Specify path to file with baseline content.
+    2. `--baseline <PATH>` Specify path to file with baseline content.
 - Changed
   - For the `--config` option, the default value is now `pyproject.toml`.
 - Full diff

README.md

@@ -39,12 +39,12 @@ here: [https://jsh9.github.io/pydoclint](https://jsh9.github.io/pydoclint)
 The corresponding Github repository of _pydoclint_ is:
 [https://github.com/jsh9/pydoclint](https://github.com/jsh9/pydoclint)
 
+<!--TOC-->
+
 ______________________________________________________________________
 
 **Table of Contents**
 
-<!--TOC-->
-
 - [1. Installation](#1-installation)
 - [2. Usage](#2-usage)
   - [2.1. As a native command line tool](#21-as-a-native-command-line-tool)
@@ -63,6 +63,8 @@ ______________________________________________________________________
 - [4. Additional notes for users](#4-additional-notes-for-users)
 - [5. Notes for developers](#5-notes-for-developers)
 
+______________________________________________________________________
+
 <!--TOC-->
 
 ## 1. Installation

docs/checking_class_attributes.md

@@ -1,5 +1,19 @@
 # Checking class attributes
 
+<!--TOC-->
+
+______________________________________________________________________
+
+**Table of Contents**
+
+- [1. Numpy style](#1-numpy-style)
+- [2. Google style](#2-google-style)
+- [3. Sphinx style](#3-sphinx-style)
+
+______________________________________________________________________
+
+<!--TOC-->
+
 Class attributes are similar to function arguments. They look like this:
 
 ```python
@@ -66,7 +80,7 @@ From this example, we can see a few things:
 
 1. The class attributes should be put in a different docstring section than the
    argument passed into the class constructor (`__init__()`)
-1. Both the class attributes and the input arguments to `__init__()` are in the
+2. Both the class attributes and the input arguments to `__init__()` are in the
    same docstring. (This is assuming the _pydoclint_ option
    `--allow-init-docstring` is `False`)
 

docs/config_options.md

@@ -7,10 +7,12 @@ For how to actually implement these options in your commands, please read this
 page:
 [How to configure _pydoclint_](https://jsh9.github.io/pydoclint/how_to_config.html).
 
-**Table of Contents**
-
 <!--TOC-->
 
+______________________________________________________________________
+
+**Table of Contents**
+
 - [1. `--quiet` (shortform: `-q`)](#1---quiet-shortform--q)
 - [2. `--exclude`](#2---exclude)
 - [3. `--style`](#3---style)
@@ -38,6 +40,8 @@ page:
 - [25. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)](#25---show-filenames-in-every-violation-message-shortform--sfn-default-false)
 - [26. `--config` (default: `pyproject.toml`)](#26---config-default-pyprojecttoml)
 
+______________________________________________________________________
+
 <!--TOC-->
 
 ## 1. `--quiet` (shortform: `-q`)

docs/how_to_config.md

@@ -1,5 +1,20 @@
 # How to configure _pydoclint_
 
+<!--TOC-->
+
+______________________________________________________________________
+
+**Table of Contents**
+
+- [1. All configuration options](#1-all-configuration-options)
+- [2. Specifying options inline](#2-specifying-options-inline)
+- [3. Specifying options in a configuration file](#3-specifying-options-in-a-configuration-file)
+- [4. Specifying options in `.pre-commit-config.yaml`](#4-specifying-options-in-pre-commit-configyaml)
+
+______________________________________________________________________
+
+<!--TOC-->
+
 This document shows you how to configure _pydoclint_.
 
 ## 1. All configuration options

docs/how_to_ignore.md

@@ -1,12 +1,26 @@
 # How to ignore certain violations
 
-## As a native tool
+<!--TOC-->
+
+______________________________________________________________________
+
+**Table of Contents**
+
+- [1. As a native tool](#1-as-a-native-tool)
+- [2. As a _flake8_ plugin](#2-as-a-flake8-plugin)
+  - [2.1. Usage with Ruff](#21-usage-with-ruff)
+
+______________________________________________________________________
+
+<!--TOC-->
+
+## 1. As a native tool
 
 Currently, pydoclint does not support ignoring certain violations as a native
 tool. Please use it as a _flake8_ plugin to achieve that, or feel free to
 contribute this feature.
 
-## As a _flake8_ plugin
+## 2. As a _flake8_ plugin
 
 In _flake8_ mode (meaning that you use _pydoclint_ as a flake8 plugin), if
 you'd like to ignore a specific violation code (such as `DOC201` and `DOC301`)
@@ -35,7 +49,7 @@ All the usage is consistent with how you would use _flake8_. Please read the
 official _flake8_ documentation for full details:
 https://flake8.pycqa.org/en/latest/user/violations.html.
 
-### Usage with [Ruff](https://github.com/astral-sh/ruff)
+### 2.1. Usage with [Ruff](https://github.com/astral-sh/ruff)
 
 With `ruff>=0.1.3`, allowlist `DOC` codes using the
 [`external` setting](https://docs.astral.sh/ruff/settings/#external):