ADD TO: publish action / auto-generate table of contents

jrfnl · jrfnl · commit 630cf524c8c2 · 2025-06-15T19:39:06.000+02:00
diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml
@@ -35,10 +35,16 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Install DocToc table of contents generator
+        run: npm install -g doctoc
+
       - name: Copy wiki files to temporary location
         shell: bash
         run: cp -v -a wiki _wiki
 
+      - name: Update tables of contents
+        run: doctoc ./_wiki/ --github --maxlevel 4 --update-only
+
       - name: Deploy to wiki
         uses: Andrew-Chen-Wang/github-wiki-action@v4
         with:
diff --git a/wiki/About-Standards-for-PHP_CodeSniffer.md b/wiki/About-Standards-for-PHP_CodeSniffer.md
@@ -1,15 +1,7 @@
 ## Table of contents
 
-* [A Project ruleset or a standard ?](#a-project-ruleset-or-a-standard-)
-* [How does PHP_CodeSniffer determine which standard or ruleset to apply ?](#how-does-php_codesniffer-determine-which-standard-or-ruleset-to-apply-)
-* [About standards](#about-standards)
-* [Creating an external standard for PHP_CodeSniffer](#creating-an-external-standard-for-php_codesniffer)
-* [Creating new rules](#creating-new-rules)
-    * [Naming conventions](#naming-conventions)
-        * [1. Directory structure](#1-directory-structure)
-        * [2. Sniff file name](#2-sniff-file-name)
-        * [3. Namespace and class name](#3-namespace-and-class-name)
-        * [Examples](#examples)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Advanced-Usage.md b/wiki/Advanced-Usage.md
@@ -1,24 +1,7 @@
 ## Table of contents
 
-* [Specifying Valid File Extensions](#specifying-valid-file-extensions)
-* [Ignoring Files and Folders](#ignoring-files-and-folders)
-* [Ignoring Parts of a File](#ignoring-parts-of-a-file)
-* [Limiting Results to Specific Sniffs](#limiting-results-to-specific-sniffs)
-* [Filtering Errors and Warnings Based on Severity](#filtering-errors-and-warnings-based-on-severity)
-* [Replacing Tabs with Spaces](#replacing-tabs-with-spaces)
-* [Specifying an Encoding](#specifying-an-encoding)
-* [Using a Bootstrap File](#using-a-bootstrap-file)
-* [Using a Default Configuration File](#using-a-default-configuration-file)
-* [Specifying php.ini Settings](#specifying-phpini-settings)
-* [Setting Configuration Options](#setting-configuration-options)
-* [Deleting Configuration Options](#deleting-configuration-options)
-* [Viewing Configuration Options](#viewing-configuration-options)
-* [Printing Verbose Tokeniser Output](#printing-verbose-tokeniser-output)
-    * [The Scope Map](#the-scope-map)
-    * [The Level Map](#the-level-map)
-* [Printing Verbose Token Processing Output](#printing-verbose-token-processing-output)
-* [Quieting Output](#quieting-output)
-* [Understanding the Exit Codes](#understanding-the-exit-codes)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Configuration-Options.md b/wiki/Configuration-Options.md
@@ -1,27 +1,7 @@
 ## Table of contents
 
-* [Setting the default coding standard](#setting-the-default-coding-standard)
-* [Setting the default report format](#setting-the-default-report-format)
-* [Hiding warnings by default](#hiding-warnings-by-default)
-* [Showing progress by default](#showing-progress-by-default)
-* [Using colors in output by default](#using-colors-in-output-by-default)
-* [Changing the default severity levels](#changing-the-default-severity-levels)
-* [Setting the default report width](#setting-the-default-report-width)
-* [Setting the default encoding](#setting-the-default-encoding)
-* [Setting the default tab width](#setting-the-default-tab-width)
-* [Setting the installed standard paths](#setting-the-installed-standard-paths)
-* [Setting the PHP version](#setting-the-php-version)
-* [Ignoring errors when generating the exit code](#ignoring-errors-when-generating-the-exit-code)
-* [Ignoring warnings when generating the exit code](#ignoring-warnings-when-generating-the-exit-code)
-* [Ignoring non-auto-fixable issues when generating the exit code (PHP_CodeSniffer >= 4.0.0)](#ignoring-non-auto-fixable-issues-when-generating-the-exit-code-php_codesniffer--400)
-* Setting tool paths
-    * [CSSLint](#setting-the-path-to-csslint)
-    * [Google Closure Linter](#setting-the-path-to-the-google-closure-linter)
-    * [PHP](#setting-the-path-to-php)
-    * [JSHint](#setting-the-path-to-jshint)
-    * [JSLint](#setting-the-path-to-jslint)
-    * [JavaScript Lint](#setting-the-path-to-javascript-lint)
-    * [Zend Code Analyzer](#setting-the-path-to-the-zend-code-analyzer)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Customisable-Sniff-Properties.md b/wiki/Customisable-Sniff-Properties.md
@@ -4,70 +4,8 @@ For more information about changing sniff behaviour by customising your ruleset,
 
 ## Table of contents
 
-* [Generic Sniffs](#generic-sniffs)
-    * [Generic.Arrays.ArrayIndent](#genericarraysarrayindent)
-    * [Generic.CodeAnalysis.UnusedFunctionParameter](#genericcodeanalysisunusedfunctionparameter)
-    * [Generic.ControlStructures.InlineControlStructure](#genericcontrolstructuresinlinecontrolstructure)
-    * [Generic.Debug.ClosureLinter](#genericdebugclosurelinter)
-    * [Generic.Debug.ESLint](#genericdebugeslint)
-    * [Generic.Files.LineEndings](#genericfileslineendings)
-    * [Generic.Files.LineLength](#genericfileslinelength)
-    * [Generic.Formatting.MultipleStatementAlignment](#genericformattingmultiplestatementalignment)
-    * [Generic.Formatting.SpaceAfterCast](#genericformattingspaceaftercast)
-    * [Generic.Formatting.SpaceAfterNot](#genericformattingspaceafternot)
-    * [Generic.Functions.OpeningFunctionBraceBsdAllman](#genericfunctionsopeningfunctionbracebsdallman)
-    * [Generic.Functions.OpeningFunctionBraceKernighanRitchie](#genericfunctionsopeningfunctionbracekernighanritchie)
-    * [Generic.Metrics.CyclomaticComplexity](#genericmetricscyclomaticcomplexity)
-    * [Generic.Metrics.NestingLevel](#genericmetricsnestinglevel)
-    * [Generic.NamingConventions.CamelCapsFunctionName](#genericnamingconventionscamelcapsfunctionname)
-    * [Generic.PHP.ForbiddenFunctions](#genericphpforbiddenfunctions)
-    * [Generic.PHP.NoSilencedErrors](#genericphpnosilencederrors)
-    * [Generic.Strings.UnnecessaryStringConcat](#genericstringsunnecessarystringconcat)
-    * [Generic.WhiteSpace.ArbitraryParenthesesSpacing](#genericwhitespacearbitraryparenthesesspacing)
-    * [Generic.WhiteSpace.ScopeIndent](#genericwhitespacescopeindent)
-    * [Generic.WhiteSpace.SpreadOperatorSpacingAfter](#genericwhitespacespreadoperatorspacingafter)
-* [PEAR Sniffs](#pear-sniffs)
-    * [PEAR.Commenting.FunctionComment](#pearcommentingfunctioncomment)
-    * [PEAR.ControlStructures.ControlSignature](#pearcontrolstructurescontrolsignature)
-    * [PEAR.ControlStructures.MultiLineCondition](#pearcontrolstructuresmultilinecondition)
-    * [PEAR.Formatting.MultiLineAssignment](#pearformattingmultilineassignment)
-    * [PEAR.Functions.FunctionCallSignature](#pearfunctionsfunctioncallsignature)
-    * [PEAR.Functions.FunctionDeclaration](#pearfunctionsfunctiondeclaration)
-    * [PEAR.WhiteSpace.ObjectOperatorIndent](#pearwhitespaceobjectoperatorindent)
-    * [PEAR.WhiteSpace.ScopeClosingBrace](#pearwhitespacescopeclosingbrace)
-    * [PEAR.WhiteSpace.ScopeIndent](#pearwhitespacescopeindent)
-* [PSR2 Sniffs](#psr2-sniffs)
-    * [PSR2.Classes.ClassDeclaration](#psr2classesclassdeclaration)
-    * [PSR2.ControlStructures.ControlStructureSpacing](#psr2controlstructurescontrolstructurespacing)
-    * [PSR2.ControlStructures.SwitchDeclaration](#psr2controlstructuresswitchdeclaration)
-    * [PSR2.Methods.FunctionCallSignature](#psr2methodsfunctioncallsignature)
-* [PSR12 Sniffs](#psr12-sniffs)
-    * [PSR12.Classes.AnonClassDeclaration](#psr12classesanonclassdeclaration)
-    * [PSR12.ControlStructures.BooleanOperatorPlacement](#psr12controlstructuresbooleanoperatorplacement)
-    * [PSR12.ControlStructures.ControlStructureSpacing](#psr12controlstructurescontrolstructurespacing)
-    * [PSR12.Namespaces.CompoundNamespaceDepth](#psr12namespacescompoundnamespacedepth)
-    * [PSR12.Operators.OperatorSpacing](#psr12operatorsoperatorspacing)
-* [Squiz Sniffs](#squiz-sniffs)
-    * [Squiz.Classes.ClassDeclaration](#squizclassesclassdeclaration)
-    * [Squiz.Commenting.FunctionComment](#squizcommentingfunctioncomment)
-    * [Squiz.Commenting.LongConditionClosingComment](#squizcommentinglongconditionclosingcomment)
-    * [Squiz.ControlStructures.ControlSignature](#squizcontrolstructurescontrolsignature)
-    * [Squiz.ControlStructures.ForEachLoopDeclaration](#squizcontrolstructuresforeachloopdeclaration)
-    * [Squiz.ControlStructures.ForLoopDeclaration](#squizcontrolstructuresforloopdeclaration)
-    * [Squiz.ControlStructures.SwitchDeclaration](#squizcontrolstructuresswitchdeclaration)
-    * [Squiz.CSS.ForbiddenStyles](#squizcssforbiddenstyles)
-    * [Squiz.CSS.Indentation](#squizcssindentation)
-    * [Squiz.Functions.FunctionDeclaration](#squizfunctionsfunctiondeclaration)
-    * [Squiz.Functions.FunctionDeclarationArgumentSpacing](#squizfunctionsfunctiondeclarationargumentspacing)
-    * [Squiz.PHP.CommentedOutCode](#squizphpcommentedoutcode)
-    * [Squiz.PHP.DiscouragedFunctions](#squizphpdiscouragedfunctions)
-    * [Squiz.PHP.ForbiddenFunctions](#squizphpforbiddenfunctions)
-    * [Squiz.Strings.ConcatenationSpacing](#squizstringsconcatenationspacing)
-    * [Squiz.WhiteSpace.FunctionSpacing](#squizwhitespacefunctionspacing)
-    * [Squiz.WhiteSpace.MemberVarSpacing](#squizwhitespacemembervarspacing)
-    * [Squiz.WhiteSpace.ObjectOperatorSpacing](#squizwhitespaceobjectoperatorspacing)
-    * [Squiz.WhiteSpace.OperatorSpacing](#squizwhitespaceoperatorspacing)
-    * [Squiz.WhiteSpace.SuperfluousWhitespace](#squizwhitespacesuperfluouswhitespace)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/FAQ.md b/wiki/FAQ.md
@@ -1,11 +1,7 @@
 ## Table of contents
 
-* [Does PHP_CodeSniffer perform any code coverage or unit testing?](#does-php_codesniffer-perform-any-code-coverage-or-unit-testing)
-* [My code is fine! Why do I need PHP_CodeSniffer?](#my-code-is-fine-why-do-i-need-php_codesniffer)
-* [Does PHP_CodeSniffer parse my code to ensure it will execute?](#does-php_codesniffer-parse-my-code-to-ensure-it-will-execute)
-* [I don't agree with your coding standards! Can I make PHP_CodeSniffer enforce my own?](#i-dont-agree-with-your-coding-standards-can-i-make-php_codesniffer-enforce-my-own)
-* [How come PHP_CodeSniffer reported errors, I fixed them, now I get even more?](#how-come-php_codesniffer-reported-errors-i-fixed-them-now-i-get-even-more)
-* [What does PHP_CodeSniffer use to tokenize my code?](#what-does-php_codesniffer-use-to-tokenize-my-code)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Fixing-Errors-Automatically.md b/wiki/Fixing-Errors-Automatically.md
@@ -1,8 +1,7 @@
 ## Table of contents
 
-* [About Automatic Fixing](#about-automatic-fixing)
-* [Using the PHP Code Beautifier and Fixer](#using-the-php-code-beautifier-and-fixer)
-* [Viewing Debug Information](#viewing-debug-information)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Usage.md b/wiki/Usage.md
@@ -1,12 +1,7 @@
 ## Table of contents
 
-* [Getting Help from the Command Line](#getting-help-from-the-command-line)
-* [Checking Files and Folders](#checking-files-and-folders)
-* [Printing a Summary Report](#printing-a-summary-report)
-* [Printing Progress Information](#printing-progress-information)
-* [Specifying a Coding Standard](#specifying-a-coding-standard)
-* [Printing a List of Installed Coding Standards](#printing-a-list-of-installed-coding-standards)
-* [Listing Sniffs Inside a Coding Standard](#listing-sniffs-inside-a-coding-standard)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Version-3.0-Upgrade-Guide.md b/wiki/Version-3.0-Upgrade-Guide.md
@@ -7,20 +7,8 @@ PHP_CodeSniffer version 3 contains a large number of core changes and breaks bac
 
 ## Table of contents
 
-* [Upgrading Custom Sniffs](#upgrading-custom-sniffs)
-    * [Extending Other Sniffs](#extending-other-sniffs)
-    * [Extending the Included Abstract Sniffs](#extending-the-included-abstract-sniffs)
-        * [AbstractVariableSniff](#abstractvariablesniff)
-        * [AbstractPatternSniff](#abstractpatternsniff)
-        * [AbstractScopeSniff](#abstractscopesniff)
-    * [New Class Names](#new-class-names)
-        * [PHP_CodeSniffer_File](#php_codesniffer_file)
-        * [PHP_CodeSniffer_Tokens](#php_codesniffer_tokens)
-        * [PHP_CodeSniffer](#php_codesniffer)
-* [Upgrading Unit Tests](#upgrading-unit-tests)
-    * [Setting CLI Values](#setting-cli-values)
-* [Upgrading Custom Reports](#upgrading-custom-reports)
-    * [Supporting Concurrency](#supporting-concurrency)
+<!-- START doctoc -->
+<!-- END doctoc -->
 
 ***
 
diff --git a/wiki/Version-4.0-Developer-Upgrade-Guide.md b/wiki/Version-4.0-Developer-Upgrade-Guide.md
@@ -14,38 +14,10 @@ There is a separate [[Upgrade Guide for Ruleset Maintainers and End-Users|Versio
 
 ## Table of contents
 
-* [Should I upgrade ?](#should-i-upgrade-)
-    * [Upgrade strategies](#upgrade-strategies)
-* [Upgrading the ruleset.xml file](#upgrading-the-rulesetxml-file)
-* [Upgrading Standards](#upgrading-standards)
-    * [Support for external standards named "Internal" has been removed](#support-for-external-standards-named-internal-has-been-removed)
-* [Upgrading Custom Sniffs](#upgrading-custom-sniffs)
-    * [Sniffs need to comply with the naming conventions](#sniffs-need-to-comply-with-the-naming-conventions)
-    * [Sniffs must implement the `PHP_CodeSniffer\Sniffs\Sniff` interface](#sniffs-must-implement-the-php_codesniffersniffssniff-interface)
-    * [Support for JS/CSS has been removed](#support-for-jscss-has-been-removed)
-    * [Property type casting has been made more consistent](#property-type-casting-has-been-made-more-consistent)
-    * [Changed Methods](#changed-methods)
-        * [File::getDeclarationName()](#filegetdeclarationname)
-        * [File::getMemberProperties()](#filegetmemberproperties)
-        * [Config::setConfigData() is no longer static](#configsetconfigdata-is-no-longer-static)
-    * [Tokens class changes](#tokens-class-changes)
-        * [Token arrays are now class constants](#token-arrays-are-now-class-constants)
-        * [Removed Tokens](#removed-tokens)
-    * [Tokenizer Changes](#tokenizer-changes)
-        * [T_USE (for closures), T_ISSET, T_UNSET, T_EMPTY, T_EVAL, T_EXIT are parenthesis owners](#t_use-for-closures-t_isset-t_unset-t_empty-t_eval-t_exit-are-parenthesis-owners)
-        * [Namespaced Names](#namespaced-names)
-        * [T_STATIC](#t_static)
-        * [T_OPEN_TAG](#t_open_tag)
-        * [`goto`](#goto)
-        * [Other Tokenizer Changes](#other-tokenizer-changes)
-    * [Changes to abstract sniffs](#changes-to-abstract-sniffs)
-    * [Changes to PHPCS native sniffs](#changes-to-phpcs-native-sniffs)
-        * [Various sniffs listen to fewer tokens](#various-sniffs-listen-to-fewer-tokens)
-        * [PHP_CodeSniffer\Standards\Squiz\Sniffs\Classes\SelfMemberReferenceSniff](#php_codesnifferstandardssquizsniffsclassesselfmemberreferencesniff)
-* [Miscellaneous other changes which may affect code extending PHP_CodeSniffer](#miscellaneous-other-changes-which-may-affect-code-extending-php_codesniffer)
-* [Unit Tests](#unit-tests)
-    * [For standards using their own test framework](#for-standards-using-their-own-test-framework)
-    * [For standards using the PHPCS native test framework](#for-standards-using-the-phpcs-native-test-framework)
+<!-- START doctoc -->
+<!-- END doctoc -->
+
+***
 
 ## Should I upgrade ?
 
@@ -517,12 +489,12 @@ The `protected` `getDeclarationNameWithNamespace()` and `getNamespaceOfScope()`
 * The `PHP_CodeSniffer\Reporter::$totalFixable` and `Reporter::$totalFixed` properties are deprecated and should no longer be used.  
     Use respectively `(Reporter::$totalFixableErrors + Reporter::$totalFixableWarnings)` and `(Reporter::$totalFixedErrors + Reporter::$totalFixedWarnings)` instead.
 
-* `PHP_CodeSniffer\Ruleset::setSniffProperty()`: the BC-layer supporting the old array format for the `$settings` parameter for the method has been removed.  
+* `PHP_CodeSniffer\Ruleset::setSniffProperty()`: the BC-layer supporting the old array format for the `$settings` parameter for the method has been removed.
     The `$settings` parameter must be passed as an array with the following two keys: `'scope'` and `'value'`, with `'scope'` being set to either `'sniff'` or `'standard'`, and `'value'` containing the new property value.  
     Also see [squizlabs/PHP_CodeSniffer#3629](https://github.com/squizlabs/PHP_CodeSniffer/pull/3629).
 
 * Various class properties have been replaced with class constants. Where these were in the public API (= the below list), the properties still exist, but are now (soft) deprecated and will be removed in PHP_CodeSniffer 5.0.  
-    The visibility of the (deprecated) properties and their class constant replacements is the same.  
+    The visibility of the (deprecated) properties and their class constant replacements is the same.
     If you previously overloaded one of these properties in a custom sniff extending one of the affected sniffs, you will now need to overload the class constant.  
     To obtain cross-version compatibility with PHPCS 3.x as well as 4.x, you may need to overload both the property as well as the constant.
 
diff --git a/wiki/Version-4.0-User-Upgrade-Guide.md b/wiki/Version-4.0-User-Upgrade-Guide.md
@@ -10,27 +10,10 @@ There is a separate [[Upgrade Guide for Sniff Developers and Integrators|Version
 
 ## Table of contents
 
-* [Should I upgrade ?](#should-i-upgrade-)
-    * [External Standards](#external-standards)
-* [How do I upgrade ?](#how-do-i-upgrade-)
-    * [OMG BBQ, I'm inundated by deprecation notices from PHP_CodeSniffer 3.13.x!](#omg-bbq-im-inundated-by-deprecation-notices-from-php_codesniffer-313x)
-* [Upgrading step by step](#upgrading-step-by-step)
-    * [The minimum PHP version is now PHP 7.2.0](#the-minimum-php-version-is-now-php-720)
-    * [Ruleset processing changes](#ruleset-processing-changes)
-    * [Support for scanning JS/CSS files has been removed](#support-for-scanning-jscss-files-has-been-removed)
-    * [Setting array properties for sniffs](#setting-array-properties-for-sniffs)
-    * [Removed sniffs](#removed-sniffs)
-    * [Removed error codes](#removed-error-codes)
-    * [Changed error codes](#changed-error-codes)
-    * [Removed sniff properties](#removed-sniff-properties)
-    * [Ignore Annotation syntax](#ignore-annotation-syntax)
-    * [Exit codes](#exit-codes)
-    * [Branch rename in the PHP_CodeSniffer repo](#upcoming-branch-rename-in-the-php_codesniffer-repo)
-* [Notable other changes and new features](#notable-other-changes-and-new-features)
-    * [Progress, error and debug output is now send to STDERR](#progress-error-and-debug-output-is-now-send-to-stderr)
-    * [Files without extension can now be scanned](#files-without-extension-can-now-be-scanned)
-    * [Array properties can now extend default property values](#array-properties-can-now-extend-default-property-values)
-    * [My scans are failing on a "No files were checked" error...](#my-scans-are-failing-on-a-no-files-were-checked-error)
+<!-- START doctoc -->
+<!-- END doctoc -->
+
+***
 
 ## Should I upgrade ?
 
