Merge pull request #5031 from MikeMcQuaid/docs-html-proofer

docs: check links with `html-proofer`

docs/.ruby-version

@@ -1 +1 @@
-2.4.1
+2.5.1

docs/Brew-Test-Bot-For-Core-Contributors.md

@@ -4,7 +4,7 @@ If a build has run and passed on `brew test-bot` then it can be used to quickly
 
 There are two types of Jenkins jobs you will interact with:
 
-## [Homebrew Core Pull Requests](https://jenkins.brew.sh/job/Homebrew%20Core/)
+## [Homebrew Core Pull Requests](https://jenkins.brew.sh/job/Homebrew%20Core%20Pull%20Requests/)
 This job automatically builds any pull requests submitted to Homebrew/homebrew-core. On success or failure it updates the pull request status (see more details on the [main Brew Test Bot documentation page](Brew-Test-Bot.md)). On a successful build it automatically uploads bottles.
 
 ## [Homebrew Testing](https://jenkins.brew.sh/job/Homebrew%20Testing/)

docs/Gemfile

@@ -1,3 +1,8 @@
 source "https://rubygems.org"
 
 gem "github-pages", group: :jekyll_plugins
+
+group :test do
+  gem "html-proofer"
+  gem "rake"
+end

docs/Gemfile.lock

@@ -13,6 +13,7 @@ GEM
       execjs
     coffee-script-source (1.11.1)
     colorator (1.1.0)
+    colorize (0.8.1)
     commonmarker (0.17.13)
       ruby-enum (~> 0.5)
     concurrent-ruby (1.0.5)
@@ -84,6 +85,15 @@ GEM
     html-pipeline (2.8.4)
       activesupport (>= 2)
       nokogiri (>= 1.4)
+    html-proofer (3.9.2)
+      activesupport (>= 4.2, < 6.0)
+      addressable (~> 2.3)
+      colorize (~> 0.8)
+      mercenary (~> 0.3.2)
+      nokogiri (~> 1.8.1)
+      parallel (~> 1.3)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
     http_parser.rb (0.6.0)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
@@ -209,9 +219,11 @@ GEM
       mini_portile2 (~> 2.3.0)
     octokit (4.12.0)
       sawyer (~> 0.8.0, >= 0.5.3)
+    parallel (1.12.1)
     pathutil (0.16.1)
       forwardable-extended (~> 2.6)
     public_suffix (2.0.5)
+    rake (12.3.1)
     rb-fsevent (0.10.3)
     rb-inotify (0.9.10)
       ffi (>= 0.5.0, < 2)
@@ -237,12 +249,15 @@ GEM
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
     unicode-display_width (1.4.0)
+    yell (2.0.7)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   github-pages
+  html-proofer
+  rake
 
 BUNDLED WITH
-   1.16.1
+   1.16.4

docs/Maintainer-Guidelines.md

@@ -140,7 +140,7 @@ All communication should ideally occur in public on GitHub. Where this is not po
 
 This makes it easier for other maintainers, contributors and users to follow along with what we're doing (and, more importantly, why we're doing it) and means that decisions have a linkable URL.
 
-All maintainers (and lead maintainer) communication through any medium is bound by [Homebrew's Code of Conduct](CODE_OF_CONDUCT.md#code-of-conduct). Abusive behaviour towards other maintainers, contributors or users will not be tolerated; the maintainer will be given a warning and if their behaviour continues they will be removed as a maintainer.
+All maintainers (and lead maintainer) communication through any medium is bound by [Homebrew's Code of Conduct](https://github.com/Homebrew/brew/blob/master/CODE_OF_CONDUCT.md#code-of-conduct). Abusive behaviour towards other maintainers, contributors or users will not be tolerated; the maintainer will be given a warning and if their behaviour continues they will be removed as a maintainer.
 
 Maintainers should feel free to pleasantly disagree with the work and decisions of other maintainers. Healthy, friendly, technical disagreement between maintainers is actively encouraged and should occur in public on the issue tracker to make the project better. Interpersonal issues should be handled privately in Slack, ideally with moderation. If work or decisions are insufficiently documented or explained any maintainer or contributor should feel free to ask for clarification. No maintainer may ever justify a decision with e.g. "because I say so" or "it was I who did X" alone. Off-topic discussions on the issue tracker, [bike-shedding](https://en.wikipedia.org/wiki/Law_of_triviality) and personal attacks are forbidden.
 

docs/Prose-Style-Guidelines.md

@@ -16,7 +16,7 @@ Homebrew's audience includes users with a wide range of education and experience
 
 We strive for "correct" but not "fancy" usage. Think newspaper article, not academic paper.
 
-This is a set of guidelines to be applied using human judgment, not a set of hard and fast rules. It is like [The Economist's Style Guide](https://www.economist.com/styleguide/introduction) or [Garner's Modern American Usage](https://en.wikipedia.org/wiki/Garner's_Modern_American_Usage). It is less like the [Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide). All guidelines here are open to interpretation and discussion. 100% conformance to these guidelines is *not* a goal.
+This is a set of guidelines to be applied using human judgment, not a set of hard and fast rules. It is like [The Economist's Style Guide](https://web.archive.org/web/20170830001125/https://www.economist.com/styleguide/introduction) or [Garner's Modern American Usage](https://en.wikipedia.org/wiki/Garner's_Modern_American_Usage). It is less like the [Ruby Style Guide](https://github.com/bbatsov/ruby-style-guide). All guidelines here are open to interpretation and discussion. 100% conformance to these guidelines is *not* a goal.
 
 The intent of this document is to help authors make decisions about clarity, style, and consistency. It is not to help settle arguments about who knows English better. Don't use this document to be a jerk.
 

docs/Python-for-Formula-Authors.md

@@ -30,7 +30,7 @@ No explicit Python dependency is needed on recent OS versions since `/usr/bin` i
 
 Applications should be installed into a Python [virtualenv](https://virtualenv.pypa.io/en/stable/) environment rooted in `libexec`. This prevents the app's Python modules from contaminating the system site-packages and vice versa.
 
-All of the Python module dependencies of the application (and their dependencies, recursively) should be declared as `resource`s in the formula and installed into the virtualenv, as well. Each dependency should be explicitly specified; please do not rely on `setup.py` or `pip` to perform automatic dependency resolution, for the [reasons described here](Acceptable-Formulae.md#we-dont-like-install-scripts-that-download-things).
+All of the Python module dependencies of the application (and their dependencies, recursively) should be declared as `resource`s in the formula and installed into the virtualenv, as well. Each dependency should be explicitly specified; please do not rely on `setup.py` or `pip` to perform automatic dependency resolution, for the [reasons described here](Acceptable-Formulae.md#we-dont-like-install-scripts-that-download-unversioned-things).
 
 You can use [homebrew-pypi-poet](https://pypi.python.org/pypi/homebrew-pypi-poet) to help you write resource stanzas. To use it, set up a virtualenv and install your package and all its dependencies. Then, `pip install homebrew-pypi-poet` into the same virtualenv. Running `poet some_package` will generate the necessary resource stanzas. You can do this like:
 

docs/Rakefile

@@ -0,0 +1,31 @@
+require "rake"
+
+task default: :build
+
+desc "Build the site."
+task :build do
+  sh "jekyll", "build"
+end
+
+desc "Run html proofer to validate the HTML output."
+task test: :build do
+  require "html-proofer"
+  HTMLProofer.check_directory(
+    "./_site",
+    parallel: { in_threads: 4 },
+    favicon: true,
+    http_status_ignore: [0, 403],
+    assume_extension: true,
+    check_favicon: true,
+    check_opengraph: true,
+    check_html: true,
+    check_img_http: true,
+    file_ignore: [
+      %r{Kickstarter-Supporters},
+    ],
+    url_ignore: [
+      "http://formulae.brew.sh",
+      %r{https://github.com/Homebrew/brew/edit/gh-pages//},
+    ]
+  ).run
+end