Bug 1825715 - Add section about ignoring formatting to ESLint docs. r=Gijs

This also does a general clean-up of the ESLint doc.

Differential Revision: https://phabricator.services.mozilla.com/D174218

docs/code-quality/lint/linters/eslint.rst

@@ -23,7 +23,7 @@ See the `Usage guide`_ for more options.
 Understanding Rules and Errors
 ------------------------------
 
-* Only some files are linted, see the `configuration`_ for details.
+* Only some files are linted, see the :searchfox:`configuration <tools/lint/eslint.yml>` for details.
 
   * By design we do not lint/format reftests not crashtests as these are specially crafted tests.
 
@@ -55,6 +55,8 @@ I am getting a linter error "Unknown Services member property"
 Make sure to add any new Services to ``tools/lint/eslint/eslint-plugin-mozilla/lib/services.json``. For example by copying from
 ``<objdir>/xpcom/components/services.json`` after a build.
 
+.. _adding-tests:
+
 I'm adding tests, how do I set up the right configuration?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -89,20 +91,33 @@ I'm using an ES module
 * If it is a system module (e.g. component definition or other non-frontend code),
   use a ``.sys.mjs`` extension.
 
-This code shouldn't be linted
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This code should neither be linted nor formatted
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* If it is a third-party piece of code, please add it to `ThirdPartyPaths.txt`_.
-* If it is pre-generated file or intentionally invalid, please add it to `.eslintignore`_
+* If it is a third-party piece of code, please add it to :searchfox:`ThirdPartyPaths.txt <tools/rewriting/ThirdPartyPaths.txt>`.
+* If it is a generated file, please add it to :searchfox:`Generated.txt <tools/rewriting/Generated.txt>`.
+* If intentionally invalid, please add it to :searchfox:`.eslintignore <.eslintignore>`.
+
+This code shouldn't be formatted
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The vast majority of code should be formatted, however we allow some limited
+cases where it makes sense, for example:
+
+* A table in an array where laying it out in a table fashion makes it more readable.
+* Other structures or function calls where layout is more readable in a particular format.
+
+To disable prettier for code like this, ``// prettier-ignore`` may be used on
+the line previous to where you want it disabled.
+See the `prettier ignore docs`_ for more information.
 
 I have valid code that is failing the ``no-undef`` rule or can't be parsed
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* Please do not add this to `.eslintignore`_. Generally this can be fixed, if the following
-  tips don't help, please `seek help`_.
-* If you are adding a new test directory, make sure its name matches one of the
-  `patterns in .eslintrc.js`_. If you really can't match those, then you may need
-  to add a separate `test specific .eslintrc.js file (example)`_.
+* Please do not add this to :searchfox:`.eslintignore <.eslintignore>`. Generally
+  this can be fixed, if the following tips don't help, please `seek help`_.
+* If you are adding a new test directory, see the :ref:`section above <adding-tests>`
+
 * If you are writing a script loaded into special environment (e.g. frame script) you may need to tell ESLint to use the `environment definitions`_ for each case:
 
   * ``/* eslint-env mozilla/frame-script */``
@@ -129,8 +144,8 @@ make it easier for developers.
 Sources
 -------
 
-* `Configuration (YAML)`_
-* `Source`_
+* :searchfox:`Configuration (YAML) <tools/lint/eslint.yml>`
+* :searchfox:`Source <tools/lint/eslint/__init__.py>`
 
 Builders
 --------
@@ -184,18 +199,13 @@ For test harness issues, file bugs in Developer Infrastructure :: Lint and Forma
 .. _Prettier: https://prettier.io/
 .. _Usage guide: ../usage.html
 .. _ESLint's documentation: http://eslint.org/docs/user-guide/configuring
-.. _configuration: https://searchfox.org/mozilla-central/source/tools/lint/eslint.yml
 .. _eslint.org's rule list: http://eslint.org/docs/rules/
 .. _eslint-plugin-mozilla: eslint-plugin-mozilla.html
 .. _eslint-plugin-spidermonkey-js: eslint-plugin-spidermonkey-js.html
-.. _ThirdPartyPaths.txt: https://searchfox.org/mozilla-central/source/tools/rewriting/ThirdPartyPaths.txt
 .. _informed that it is a module: https://searchfox.org/mozilla-central/rev/9399e5832979755cd340383f4ca4069dd5fc7774/browser/base/content/.eslintrc.js
-.. _.eslintignore: https://searchfox.org/mozilla-central/source/.eslintignore
 .. _seek help: ../index.html#getting-help
 .. _patterns in .eslintrc.js: https://searchfox.org/mozilla-central/rev/9399e5832979755cd340383f4ca4069dd5fc7774/.eslintrc.js#24-38
-.. _test specific .eslintrc.js file (example): https://searchfox.org/mozilla-central/source/browser/base/content/test/about/.eslintrc.js
 .. _environment definitions: ./eslint-plugin-mozilla/environment.html
-.. _Configuration (YAML): https://searchfox.org/mozilla-central/source/tools/lint/eslint.yml
-.. _Source: https://searchfox.org/mozilla-central/source/tools/lint/eslint/__init__.py
 .. _known ones: https://searchfox.org/mozilla-central/rev/287583a4a605eee8cd2d41381ffaea7a93d7b987/.eslintrc.js#24-40
 .. _difficult for ESLint to handle: https://bugzilla.mozilla.org/show_bug.cgi?id=1379669
+.. _prettier ignore docs: https://prettier.io/docs/en/ignore.html