You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
GH Actions/publish-wiki: auto-generate table of contents (#6)
This commit adds steps to the workflow to auto-generate a GitHub wiki compatible table of contents in most wiki pages.
This reduces the risk of a TOC being out-of-date or containing incorrectly formatted links, as well as reduces the maintenance burden.
This action uses the `doctoc` pages to generate the table of contents and this can be tested locally using the same steps as used in the GH Actions workflow:
```
npm install -g doctoc
cp -v -a wiki _wiki
doctoc ./_wiki/ --github --maxlevel 4 --update-only
doctoc ./_wiki/Version-4.0-User-Upgrade-Guide.md --github --maxlevel 3 --update-only
```
Notes:
* The files are copied to a `_wiki` directory - which is `.gitignore`d - before pre-processing to reduce the risk of the source files being accidentally updated (and committed), which would undo the automation.
* The `--github` flag puts the TOC generation in GitHub compatible mode.
* The `--update-only` flag means that only markdown files containing the `<!-- START doctoc -->` and `<!-- END doctoc -->` markers will be updated and files without those markers will be left alone.
* By default, the TOC will contain all headers up to the indicated `--maxlevel`.
For the V 4.0 Dev upgrade guide, this looked weird, what with some "Upgrading" headers being at level 4 and some at level 5.
To mitigate this, a couple of headers have been turned into "bold phrases" instead.
Along the same lines, for the V 4.0 User upgrade guide, the level 4 headers were always "Upgrading". Those belong with their parent heading and IMO do not need to be separately called out in the TOC, which explains the second call to `doctoc` to overrule the TOC for that file specifically with a `--maxlevel 3` setting.
* The start/end markers have been added to all files which contained a TOC, except for one: `Reporting.md`.
The reason for this exception is that the section order in the file does not match the current TOC order, with the existing TOC order making sense from a TOC point of view, while the section order makes sense from a "types of reports most used" point of view.
Whether this page should be re-organized or not, is outside the scope of this PR.
To allow contributors to review the resulting pre-processed wiki files, the files are uploaded as an artifact when a PR dry-run is being executed and a comment is posted on the PR requesting the contributor to review the pre-processed files.
Includes adding a TOC to the Coding Standards Tutorial page and adding "back to top" links within the page.
Ref:
* https://github.com/thlorenz/doctoc
- name: Preface markdown files with warning not to edit in place
44
60
shell: bash
45
61
# yamllint disable rule:line-length
@@ -50,6 +66,43 @@ jobs:
50
66
'1i\<!--\nWARNING: DO NOT EDIT THIS FILE IN THE WIKI.\nThis wiki is updated from the https://github.com/PHPCSStandards/PHP_CodeSniffer-documentation repository.\nSubmit a PR to that repository updating the relevant file in the /wiki/ subdirectory instead.\n-->\n' {} \;
Copy file name to clipboardExpand all lines: wiki/Coding-Standard-Tutorial.md
+26Lines changed: 26 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,13 @@ In this tutorial, we will create a new coding standard with a single sniff. Our
2
2
3
3
Sniffs need to follow [strict directory layout and naming conventions](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/About-Standards-for-PHP_CodeSniffer#naming-conventions).
4
4
5
+
## Table of contents
6
+
7
+
<!-- START doctoc -->
8
+
<!-- END doctoc -->
9
+
10
+
***
11
+
5
12
## Creating the Coding Standard Directory
6
13
7
14
All sniffs in PHP_CodeSniffer must belong to a coding standard. A coding standard is a directory with a specific sub-directory structure and a `ruleset.xml` file, so creating a standard is straight-forward.
@@ -39,6 +46,9 @@ The content of the `ruleset.xml` file should, at a minimum, be the following:
39
46
> [!NOTE]
40
47
> The ruleset.xml can be left quite small, as it is in this example coding standard. For information about the other features that the `ruleset.xml` provides, see the [[Annotated ruleset]].
41
48
49
+
<palign="right"><ahref="#table-of-contents">back to top</a></p>
50
+
51
+
42
52
## Creating the Sniff
43
53
44
54
A sniff requires a single PHP file that must be placed into a sub-directory to categorise the type of check it performs. Its name should clearly describe the standard that we are enforcing and must end with `Sniff.php`. For our sniff, we will name the PHP file `DisallowHashCommentsSniff.php` and place it into a `Commenting` sub-directory to categorise this sniff as relating to commenting. Run the following commands to create the category and the sniff:
Each sniff must implement the `PHP_CodeSniffer\Sniffs\Sniff` interface so that PHP_CodeSniffer knows that it should instantiate the sniff once it's invoked. The interface defines two methods that must be implemented; `register` and `process`.
56
66
67
+
<palign="right"><ahref="#table-of-contents">back to top</a></p>
68
+
69
+
57
70
## The `register` and `process` Methods
58
71
59
72
The `register` method allows a sniff to subscribe to one or more token types that it wants to process. Once PHP_CodeSniffer encounters one of those tokens, it calls the `process` method with the `PHP_CodeSniffer\Files\File` object (a representation of the current file being checked) and the position in the stack where the token was found.
60
73
61
74
For our sniff, we are interested in single line comments. The `token_get_all` method that PHP_CodeSniffer uses to acquire the tokens within a file distinguishes doc comments and normal comments as two separate token types. Therefore, we don't have to worry about doc comments interfering with our test. The `register` method only needs to return one token type, `T_COMMENT`.
62
75
76
+
<palign="right"><ahref="#table-of-contents">back to top</a></p>
77
+
78
+
63
79
## The Token Stack
64
80
65
81
A sniff can gather more information about a token by acquiring the token stack with a call to the `getTokens` method on the `PHP_CodeSniffer\Files\File` object. This method returns an array and is indexed by the position where the token occurs in the token stack. Each element in the array represents a token. All tokens have a `code`, `type` and a `content` index in their array. The `code` value is a unique integer for the type of token. The `type` value is a string representation of the token (e.g., `'T_COMMENT'` for comment tokens). The `type` has a corresponding globally defined integer with the same name. Finally, the `content` value contains the content of the token as it appears in the code.
66
82
67
83
> [!NOTE]
68
84
> Depending on the token, the token array may contain various additional indexes with further information on a token.
69
85
86
+
<palign="right"><ahref="#table-of-contents">back to top</a></p>
87
+
88
+
70
89
## Reporting Errors
71
90
72
91
Once an error is detected, a sniff should indicate that an error has occurred by calling the `addError` method on the `PHP_CodeSniffer\Files\File` object, passing in an appropriate error message as the first argument, the position in the stack where the error was detected as the second, a code to uniquely identify the error within this sniff and an array of data used inside the error message.
73
92
Alternatively, if the violation is considered not as critical as an error, the `addWarning` method can be used.
74
93
94
+
<palign="right"><ahref="#table-of-contents">back to top</a></p>
95
+
96
+
75
97
## DisallowHashCommentsSniff.php
76
98
77
99
We now have to write the content of our sniff. The content of the `DisallowHashCommentsSniff.php` file should be the following:
@@ -135,6 +157,8 @@ public $supportedTokenizers = [
135
157
];
136
158
```
137
159
160
+
<palign="right"><ahref="#table-of-contents">back to top</a></p>
161
+
138
162
139
163
## Results
140
164
@@ -173,3 +197,5 @@ FOUND 3 ERROR(S) AFFECTING 3 LINE(S)
173
197
13 | ERROR | Hash comments are prohibited; found # Error.
Copy file name to clipboardExpand all lines: wiki/FAQ.md
+2-6Lines changed: 2 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,11 +1,7 @@
1
1
## Table of contents
2
2
3
-
*[Does PHP_CodeSniffer perform any code coverage or unit testing?](#does-php_codesniffer-perform-any-code-coverage-or-unit-testing)
4
-
*[My code is fine! Why do I need PHP_CodeSniffer?](#my-code-is-fine-why-do-i-need-php_codesniffer)
5
-
*[Does PHP_CodeSniffer parse my code to ensure it will execute?](#does-php_codesniffer-parse-my-code-to-ensure-it-will-execute)
6
-
*[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)
7
-
*[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)
8
-
*[What does PHP_CodeSniffer use to tokenize my code?](#what-does-php_codesniffer-use-to-tokenize-my-code)
0 commit comments