Add Markdown linting for line length (#831)

* add linting rule * Exclude tables and code blocks * Save editor preferences for 120 word wrap * Add a ruler a 120 in VS code. * Ignore the release notes page Too many bullets - looks a mess * Wrap a doc with rewrap extension * Wrap framework page with rewrap Had to extract one long link to the bottom. * wrap * wrap * wrap * wrap * wrap * Add rewrap extension (very helpful) * Add ruler at 120 * Recommend extension * wrap * format a table * wrap * wrap * wrapping * wraapping * wrapping * wrapping * wrapping * weapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * wrapping * last of the wrapping * Regex find/replace on note/warning formatting * Weirdly having to update some spellcheck stuff * fix formatting
nunit · Nov 7, 2023 · 61d6f51 · 61d6f51
1 parent 94be103
commit 61d6f51
Show file tree

Hide file tree

Showing 220 changed files with 5,294 additions and 2,937 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -17,7 +17,8 @@
 				"shuworks.vscode-table-formatter",
 				"ms-dotnettools.csharp",
 				"github.vscode-github-actions",
-				"ms-azuretools.vscode-docker"
+				"ms-azuretools.vscode-docker",
+				""
 			]
 		}
 	}

diff --git a/.github/linters/.markdownlint.yml b/.github/linters/.markdownlint.yml
@@ -19,7 +19,10 @@
 # Rules by id #
 ###############
 MD024: false
-MD013: false
+MD013: 
+  line_length: 120
+  code_blocks: false
+  tables: false
 MD026: false
 MD046: false # Mix of indented and fenced code blocks
 MD004: false

diff --git a/.markdownlintrc b/.markdownlintrc
@@ -1,6 +1,11 @@
 {
     "MD024": false,
-    "MD013": false,
+    "MD013": {
+        "line_length": 123,
+        "code_blocks": false,
+        "tables": false
+
+    },
     "MD026": false,
     "MD046": false,
     "MD004": false

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,24 @@
+{
+	// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+	// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+
+	// List of extensions which should be recommended for users of this workspace.
+	"recommendations": [
+		"streetsidesoftware.code-spell-checker",
+		"oderwat.indent-rainbow",
+		"mdickin.markdown-shortcuts",
+		"davidanson.vscode-markdownlint",
+		"redhat.vscode-yaml",
+		"vsls-contrib.codetour",
+		"GitHub.vscode-pull-request-github",
+		"shuworks.vscode-table-formatter",
+		"ms-dotnettools.csharp",
+		"github.vscode-github-actions",
+		"ms-azuretools.vscode-docker",
+		"stkb.rewrap"
+	],
+	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+	"unwantedRecommendations": [
+
+	]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -15,5 +15,9 @@
     "cSpell.enabled": true,
     "cSpell.enableFiletypes": [
         "aspnetcorerazor"
-    ]
+    ],
+    "editor.wordWrap": "wordWrapColumn",
+    "editor.wrappingIndent": "same",
+    "editor.wordWrapColumn": 120,
+    "editor.rulers": [120],
 }
diff --git a/cSpell.json b/cSpell.json
@@ -37,6 +37,7 @@
         "prefilter",
         "Randomizer",
         "Refactorings",
+        "reimplementation",
         "Remoting",
         "ReSharper",
         "ruleset",
@@ -151,54 +152,57 @@
         "Ihor",
         "Sychevskyi",
         "Cropp",
-        "Maddock"
+        "Maddock",
+        "Frans",
+        "Bouma",
+        "yowko"
     ],
     "patterns": [
         {
-          "name": "Markdown links",
-          "pattern": "\\((.*)\\)",
-          "description": ""
+            "name": "Markdown links",
+            "pattern": "\\((.*)\\)",
+            "description": ""
         },
         {
-          "name": "Markdown code blocks",
-          "pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx",
-          "description": "Taken from the cSpell example at https://cspell.org/configuration/patterns/#verbose-regular-expressions"
+            "name": "Markdown code blocks",
+            "pattern": "/^(\\s*`{3,}).*[\\s\\S]*?^\\1/gmx",
+            "description": "Taken from the cSpell example at https://cspell.org/configuration/patterns/#verbose-regular-expressions"
         },
         {
-          "name": "Inline code blocks",
-          "pattern": "\\`([^\\`\\r\\n]+?)\\`",
-          "description": "https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex"
+            "name": "Inline code blocks",
+            "pattern": "\\`([^\\`\\r\\n]+?)\\`",
+            "description": "https://stackoverflow.com/questions/41274241/how-to-capture-inline-markdown-code-but-not-a-markdown-code-fence-with-regex"
         },
         {
-          "name": "Link contents",
-          "pattern": "\\<a(.*)\\>",
-          "description": ""
+            "name": "Link contents",
+            "pattern": "\\<a(.*)\\>",
+            "description": ""
         },
         {
-          "name": "Snippet references",
-          "pattern": "-- snippet:(.*)",
-          "description": ""
+            "name": "Snippet references",
+            "pattern": "-- snippet:(.*)",
+            "description": ""
         },
         {
-          "name": "Snippet references 2",
-          "pattern": "\\<\\[sample:(.*)",
-          "description": "another kind of snippet reference"
+            "name": "Snippet references 2",
+            "pattern": "\\<\\[sample:(.*)",
+            "description": "another kind of snippet reference"
         },
         {
-          "name": "Multi-line code blocks",
-          "pattern": "/^\\s*```[\\s\\S]*?^\\s*```/gm"
+            "name": "Multi-line code blocks",
+            "pattern": "/^\\s*```[\\s\\S]*?^\\s*```/gm"
         },
         {
-          "name": "HTML Tags",
-          "pattern": "<[^>]*>",
-          "description": "Reference: https://stackoverflow.com/questions/11229831/regular-expression-to-remove-html-tags-from-a-string"
+            "name": "HTML Tags",
+            "pattern": "<[^>]*>",
+            "description": "Reference: https://stackoverflow.com/questions/11229831/regular-expression-to-remove-html-tags-from-a-string"
         },
         {
             "name": "UID Lines",
             "pattern": "uid: (.*)"
         }
-      ],
-      "ignoreRegExpList": [
+    ],
+    "ignoreRegExpList": [
         "Markdown links",
         "Markdown code blocks",
         "Inline code blocks",
@@ -208,5 +212,10 @@
         "Multi-line code blocks",
         "HTML Tags",
         "UID Lines"
-      ]
+    ],
+    "ignorePaths": [
+        "**/articles/nunit-engine/release-notes.md",
+        "**/articles/nunit/release-notes/framework.md",
+        "**/articles/vs-test-adapter/AdapterV*-Release-Notes.md"
+    ]
 }
diff --git a/docs/404.md b/docs/404.md
@@ -2,4 +2,5 @@
 
 We're sorry, but the page you're looking for cannot be found on the site.
 
-Feel free to [Open an issue in the NUnit Docs GitHub Repository](https://github.com/nunit/docs/issues/new) with the URL or content you expected to exist, and we'll be happy to look into it.
+Feel free to [Open an issue in the NUnit Docs GitHub Repository](https://github.com/nunit/docs/issues/new) with the URL
+or content you expected to exist, and we'll be happy to look into it.
diff --git a/docs/articles/developer-info/Best-practices-for-XML-documentation.md b/docs/articles/developer-info/Best-practices-for-XML-documentation.md
@@ -1,50 +1,65 @@
 # Best Practices for XML Documentation
 
-XML documentation has a significant impact on the end user's experience. Unlike other parts of the code, XML comments (as well as exception messages) are user-facing and highly visible. They can save valuable time and even make the difference for an end user between a confusing debugging session and no debugging needed in the first place.
+XML documentation has a significant impact on the end user's experience. Unlike other parts of the code, XML comments
+(as well as exception messages) are user-facing and highly visible. They can save valuable time and even make the
+difference for an end user between a confusing debugging session and no debugging needed in the first place.
 
 Polished and informative XML documentation provides a noticeably positive experience.
 
 ## Sentences
 
 Always end sentences with proper punctuation, typically a period.
 
-If there aren't enough words to form a sentence, it's likely that they are redundant. Try to add enough context to make a sentence to avoid anemic documentation. Rather than `The comparer`, say `Used to compare the <paramref name="items"/>.` The added clarity is desirable.
+If there aren't enough words to form a sentence, it's likely that they are redundant. Try to add enough context to make
+a sentence to avoid anemic documentation. Rather than `The comparer`, say `Used to compare the <paramref
+name="items"/>.` The added clarity is desirable.
 
 ## `<see>`, `<paramref>` and `<typeparamref>`
 
 Use `<see cref="TypeOrMember"/>`, `<paramref name="parameterName"/>` and `<typeparamref name="T"/>` whenever possible.
-The compiler checks the validity of the names and overloads. Future refactoring can be done with confidence that you aren't leaving the docs out of date.
+The compiler checks the validity of the names and overloads. Future refactoring can be done with confidence that you
+aren't leaving the docs out of date.
 
-This also provides a seamless experience by creating links in the Object Browser and intellisense and colorizes intellisense. Consider using `<see langword="null"/>` for keywords to maintain the seamlessness.
+This also provides a seamless experience by creating links in the Object Browser and intellisense and colorizes
+intellisense. Consider using `<see langword="null"/>` for keywords to maintain the seamlessness.
 
 ## `<summary>`
 
 Add a `<summary>` tag for each public type and member.
 
-However, prefer to give each type and member a really communicative name. If those names end up covering all the user could need to know, remove the `<summary>` tag (if this does not cause a build warning) to avoid super redundant documentation. If they do not, add relevant details.
+However, prefer to give each type and member a really communicative name. If those names end up covering all the user
+could need to know, remove the `<summary>` tag (if this does not cause a build warning) to avoid super redundant
+documentation. If they do not, add relevant details.
 
 ## `<param>` and `<typeparam>`
 
 Add a `<param>` tag for each parameter describing what *effect* it has (rather than what it *is*).
 
-However, prefer to give each parameter a really communicative name. If those names end up covering all the user could need to know about *all* the parameters, remove all the `<param>` tags to avoid super redundant documentation. If they do not, add relevant details to each `<param>` to the extent possible.
+However, prefer to give each parameter a really communicative name. If those names end up covering all the user could
+need to know about *all* the parameters, remove all the `<param>` tags to avoid super redundant documentation. If they
+do not, add relevant details to each `<param>` to the extent possible.
 
-The same applies to `<typeparam>` tags. They are shown by intellisense as the user enters type parameter lists exactly the way `<param>` descriptions are shown as the user enters method parameter lists. `<typeparam>` elements are just as important on generic methods as they are on generic type definitions.
+The same applies to `<typeparam>` tags. They are shown by intellisense as the user enters type parameter lists exactly
+the way `<param>` descriptions are shown as the user enters method parameter lists. `<typeparam>` elements are just as
+important on generic methods as they are on generic type definitions.
 
 ## `<returns>` and `<value>`
 
-Don't spend any time on the `<returns>` or `<value>` tags since the contents are not typically seen. Important details should all be in the `<summary>`. If the IDE auto-inserts them, just remove them.
+Don't spend any time on the `<returns>` or `<value>` tags since the contents are not typically seen. Important details
+should all be in the `<summary>`. If the IDE auto-inserts them, just remove them.
 
 ## Empty tags
 
-Do not leave any empty tags. Either remove them or fill them out. This includes the compiler's all-or-none `<param>` and `<typeparam>` tag enforcement.
+Do not leave any empty tags. Either remove them or fill them out. This includes the compiler's all-or-none `<param>` and
+`<typeparam>` tag enforcement.
 
 ## `<exception>`
 
-Consider documenting things that lead to exceptions being thrown using the `<exception>` tag.
-This can really get the end user up to speed on things that aren't immediately obvious from the method signature.
+Consider documenting things that lead to exceptions being thrown using the `<exception>` tag. This can really get the
+end user up to speed on things that aren't immediately obvious from the method signature.
 
-Sadly intellisense will only show the `<exception>` type thrown, not the message, so for important messages it's good to also include the message a second time in the summary:
+Sadly intellisense will only show the `<exception>` type thrown, not the message, so for important messages it's good to
+also include the message a second time in the summary:
 
 ```csharp
 /// <summary>