Cleanup documentation site

GitHub now nicely generates a documentation site for us at http://brew.sh/brew based on our docs folder. Optimise the output of this and the GitHub docs directory for readability and the various user groupings.
Mapgax · Jan 4, 2017 · 127e9de · 127e9de
1 parent fc11f63
commit 127e9de
Show file tree

Hide file tree

Showing 26 changed files with 237 additions and 250 deletions.
diff --git a/.gitignore b/.gitignore
@@ -38,6 +38,13 @@
 !/docs
 !/manpages
 
+# Ignore generated documentation site
+/docs/_site
+/docs/.bundle
+/docs/bin
+/docs/vendor
+/docs/Gemfile.lock
+
 # Unignore our shell completion
 !/completions
 

diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ cd "$(brew --repo)" && git fetch && git reset --hard origin/master && brew updat
 3. Or use `brew search --desc <keyword>` to browse packages from the command line.
 
 ## More Documentation
-`brew help`, `man brew` or check [our documentation](https://github.com/Homebrew/brew/tree/master/docs#readme).
+`brew help`, `man brew` or check [our documentation](https://brew.sh/brew/).
 
 ## Troubleshooting
 First, please run `brew update` and `brew doctor`.
@@ -40,9 +40,14 @@ This is our PGP key which is valid until May 24, 2017.
 ## Who Are You?
 Homebrew's lead maintainer is [Mike McQuaid](https://github.com/mikemcquaid).
 
-Homebrew's current maintainers are [Misty De Meo](https://github.com/mistydemeo), [Andrew Janke](https://github.com/apjanke), [Xu Cheng](https://github.com/xu-cheng), [Tomasz Pajor](https://github.com/nijikon), [Josh Hagins](https://github.com/jawshooah), [Baptiste Fontaine](https://github.com/bfontaine), [Markus Reiter](https://github.com/reitermarkus), [ilovezfs](https://github.com/ilovezfs), [Martin Afanasjew](https://github.com/UniqMartin), [Tom Schoonjans](https://github.com/tschoonj), [Uladzislau Shablinski](https://github.com/vladshablinsky), [Tim Smith](https://github.com/tdsmith) and [Alex Dunn](https://github.com/dunn).
+Homebrew's current maintainers are [Misty De Meo](https://github.com/mistydemeo), [Andrew Janke](https://github.com/apjanke), [Xu Cheng](https://github.com/xu-cheng), [Tomasz Pajor](https://github.com/nijikon), [Josh Hagins](https://github.com/jawshooah), [Baptiste Fontaine](https://github.com/bfontaine), [Markus Reiter](https://github.com/reitermarkus), [ilovezfs](https://github.com/ilovezfs), [Tom Schoonjans](https://github.com/tschoonj), [Uladzislau Shablinski](https://github.com/vladshablinsky), [Tim Smith](https://github.com/tdsmith) and [Alex Dunn](https://github.com/dunn).
 
-Former maintainers with significant contributions include [Dominyk Tiller](https://github.com/DomT4), [Brett Koonce](https://github.com/asparagui), [Jack Nagel](https://github.com/jacknagel), [Adam Vandenberg](https://github.com/adamv) and Homebrew's creator: [Max Howell](https://github.com/mxcl).
+Former maintainers with significant contributions include [Martin Afanasjew](https://github.com/UniqMartin), [Dominyk Tiller](https://github.com/DomT4), [Brett Koonce](https://github.com/asparagui), [Jack Nagel](https://github.com/jacknagel), [Adam Vandenberg](https://github.com/adamv) and Homebrew's creator: [Max Howell](https://github.com/mxcl).
+
+## Community
+- [discourse.brew.sh (forum)](http://discourse.brew.sh)
+- [freenode.net\#machomebrew (IRC)](irc://irc.freenode.net/#machomebrew)
+- [@MacHomebrew (Twitter)](https://twitter.com/MacHomebrew)
 
 ## License
 Code is under the [BSD 2-clause "Simplified" License](https://github.com/Homebrew/brew/tree/master/LICENSE.txt).

diff --git a/docs/.ruby-version b/docs/.ruby-version
@@ -0,0 +1 @@
+system
diff --git a/docs/Acceptable-Formulae.md b/docs/Acceptable-Formulae.md
@@ -29,16 +29,16 @@ There are exceptions:
 
 #### Examples
 
-  Formula         | Reason
-  ---             | ---
-  ruby, python, perl    | People want newer versions
-  bash            | macOS's bash is stuck at 3.2 because newer versions are licensed under GPLv3
-  zsh             | This was a mistake, but it’s too late to remove it
-  emacs, vim      | [Too popular to move to dupes](https://github.com/Homebrew/homebrew/pull/21594#issuecomment-21968819)
-  subversion      | Originally added for 10.5, but people want the latest version
-  libcurl         | Some formulae require a newer version than macOS provides
-  openssl         | macOS's openssl is deprecated & outdated.
-  libxml2         | Historically, macOS's libxml2 has been buggy
+| Formula            | Reason                                                                                                |
+|--------------------|-------------------------------------------------------------------------------------------------------|
+| ruby, python, perl | People want newer versions                                                                            |
+| bash               | macOS's bash is stuck at 3.2 because newer versions are licensed under GPLv3                          |
+| zsh                | This was a mistake, but it’s too late to remove it                                                    |
+| emacs, vim         | [Too popular to move to dupes](https://github.com/Homebrew/homebrew/pull/21594#issuecomment-21968819) |
+| subversion         | Originally added for 10.5, but people want the latest version                                         |
+| libcurl            | Some formulae require a newer version than macOS provides                                             |
+| openssl            | macOS's openssl is deprecated & outdated.                                                             |
+| libxml2            | Historically, macOS's libxml2 has been buggy                                                          |
 
 We also maintain [a tap](https://github.com/Homebrew/homebrew-dupes) that
 contains many duplicates not otherwise found in Homebrew.
@@ -80,7 +80,8 @@ useful to people. Just install the stuff! Having to faff around with
 foo-ruby foo-perl etc. sucks.
 
 ### Niche (or self-submitted) Stuff<a name="Niche_Stuff"></a>
-The software in question must be
+The software in question must be:
+
 * maintained (e.g. upstream is still making new releases)
 * known
 * stable (e.g. not declared "unstable" or "beta" by upstream)

diff --git a/docs/Analytics.md b/docs/Analytics.md
@@ -1,4 +1,4 @@
-# Homebrew's Anonymous Aggregate User Behaviour Analytics
+# Anonymous Aggregate User Behaviour Analytics
 Homebrew has begun gathering anonymous aggregate user behaviour analytics and reporting these to Google Analytics. You will be notified the first time you run `brew update` or install Homebrew.
 
 ## Why?
@@ -41,7 +41,7 @@ Homebrew's analytics are sent throughout Homebrew's execution to Google Analytic
 Homebrew's analytics are accessible to Homebrew's current maintainers. Contact @mikemcquaid if you are a maintainer and need access.
 
 ## How?
-The code is viewable in https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb and https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh. They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection.
+The code is viewable in [analytics.rb](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb) and [analytics.sh](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh). They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection.
 
 ## Opting out
 Homebrew analytics helps us maintainers and leaving it on is appreciated. However, if you want to opt out of Homebrew's analytics, you can set this variable in your environment:

diff --git a/docs/Bottles.md b/docs/Bottles.md
@@ -1,23 +1,24 @@
-# Bottles
-Bottles are Homebrew's binary packages. They are produced by installing a formula with `brew install --build-bottle $FORMULA` and then bottling it with `brew bottle $FORMULA`. This outputs the bottle DSL which should be inserted into the formula file.
+# Bottles (binary packages)
+Bottles are produced by installing a formula with `brew install --build-bottle $FORMULA` and then bottling it with `brew bottle $FORMULA`. This outputs the bottle DSL which should be inserted into the formula file.
 
-## Bottle Usage
+## Usage
 If a bottle is available and usable it will be downloaded and poured automatically when you `brew install <formula>`. If you wish to disable this you can do it by specifying `--build-from-source`.
 
 Bottles will not be used if the user requests it (see above), if the formula requests it (with `pour_bottle?`), if any options are specified on installation (bottles are all compiled with default options), if the bottle is not up to date (e.g. lacking a checksum) or the bottle's `cellar` is not `:any` or equal to the current `HOMEBREW_CELLAR`.
 
-## Bottle Creation
+## Creation
 Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mostly when people submit pull requests to Homebrew and the `bottle do` block is updated by maintainers when they `brew pull --bottle` the contents of a pull request. For the Homebrew organisations' taps they are uploaded to and downloaded from [Bintray](https://bintray.com/homebrew).
 
 By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for. (That's Core 2 for 64-bit OSs, Core for 32-bit.) This ensures that bottles are compatible with all computers you might distribute them to. If you *really* want your bottles to be optimized for something else, you can pass the `--bottle-arch=` option to build for another architecture - for example, `brew install foo --bottle-arch=penryn`. Just remember that if you build for a newer architecture some of your users might get binaries they can't run and that would be sad!
 
-## Bottle Format
+## Format
 Bottles are simple gzipped tarballs of compiled binaries. Any metadata is stored in a formula's bottle DSL and in the bottle filename (i.e. MacOS version, revision).
 
 ## Bottle DSL (Domain Specific Language)
 Bottles have a DSL to be used in formulae which is contained in the `bottle do ... end` block.
 
 A simple (and typical) example:
+
 ```ruby
 bottle do
   sha256 "4921af80137af9cc3d38fd17c9120da882448a090b0a8a3a19af3199b415bfca" => :sierra
@@ -27,6 +28,7 @@ end
 ```
 
 A full example:
+
 ```ruby
 bottle do
   root_url "https://example.com"
@@ -39,33 +41,34 @@ bottle do
 end
 ```
 
-### `root_url`
+### Root URL (`root_url`)
 Optionally contains the URL root used to calculate bottle URLs.
 By default this is omitted and the Homebrew default bottle URL root is used. This may be useful for taps which wish to provide bottles for their formulae or to cater for a non-default `HOMEBREW_CELLAR`.
 
-### `cellar`
+### Cellar (`cellar`)
 Optionally contains the value of `HOMEBREW_CELLAR` in which the bottles were built.
 Most compiled software contains references to its compiled location so cannot be simply relocated anywhere on disk. If this value is `:any` or `:any_skip_relocation` this means that the bottle can be safely installed in any Cellar as it did not contain any references to its installation Cellar. This can be omitted if a bottle is compiled (as all default Homebrew ones are) for the default `HOMEBREW_CELLAR` of `/usr/local/Cellar`
 
-### `prefix`
+### Prefix (`prefix`)
 Optionally contains the value of `HOMEBREW_PREFIX` in which the bottles were built.
 See description of `cellar`. When `cellar` is `:any` or `:any_skip_relocation` prefix should be omitted.
 
-### `rebuild`
+### Rebuild version (`rebuild`)
 Optionally contains the rebuild version of the bottle.
 Sometimes bottles may need be updated without bumping the version of the formula e.g. a new patch was applied. In that case the rebuild will have a value of 1 or more.
 
-### `sha256`
+### Checksum (`sha256`)
 Contains the SHA-256 of bottle for a particular version of macOS.
 
 ## Formula DSL
 Additionally there is a method available in the formula DSL.
 
-### `pour_bottle?`
+### Pour Bottle (`pour_bottle?`)
 Optionally returns a boolean to decide whether a bottle should be used for this formula.
 For example a bottle may break if another formula has been compiled with non-default options so this method could check for that case and return `false`.
 
 A full example:
+
 ```ruby
 pour_bottle? do
   reason "The bottle needs the Xcode CLT to be installed."

diff --git a/docs/Brew-Test-Bot-For-Core-Contributors.md b/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 Pull Requests](https://bot.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 wiki page](Brew-Test-Bot.md)). On a successful build it automatically uploads bottles.
+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://bot.brew.sh/job/Homebrew%20Testing/)
 This job is manually triggered to run [`brew test-bot`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/dev-cmd/test-bot.rb) with user-specified parameters. On a successful build it automatically uploads bottles.

diff --git a/docs/CNAME b/docs/CNAME
@@ -0,0 +1 @@
+docs.brew.sh
diff --git a/docs/Checksum_Deprecation.md b/docs/Checksum_Deprecation.md
@@ -1,5 +1,4 @@
-# Checksum Deprecation
-
+# MD5 and SHA-1 Deprecation
 During early 2015 Homebrew started the process of deprecating _SHA1_ for package
 integrity verification. Since then every formulae under the Homebrew organisation
 has been moved onto _SHA256_ verification; this includes both source packages

diff --git a/docs/Custom-GCC-and-cross-compilers.md b/docs/Custom-GCC-and-cross-compilers.md
@@ -1,4 +1,4 @@
-# Custom GCC and cross compilers
+# Custom GCC and Cross Compilers
 Homebrew depends on having an up-to-date version of Xcode because it comes with
 specific versions of build tools e.g. `clang`.
 

diff --git a/docs/External-Commands.md b/docs/External-Commands.md
@@ -7,78 +7,56 @@ $ brew mycommand --option1 --option3 formula
 
 without modifying Homebrew's internals.
 
-## COMMAND TYPES
+## Command Types
 External commands come in two flavors: Ruby commands and shell scripts.
 
 In both cases, the command file should be executable (`chmod +x`) and live somewhere in `$PATH`.
 
-### RUBY COMMANDS
+### Ruby Commands
 An external command `extcmd` implemented as a Ruby command should be named `brew-extcmd.rb`. The command is executed by doing a `require` on the full pathname. As the command is `require`d, it has full access to the Homebrew "environment", i.e. all global variables and modules that any internal command has access to.
 
 The command may `Kernel.exit` with a status code if it needs to; if it doesn't explicitly exit then Homebrew will return 0.
 
-### SHELL SCRIPTS
+### Shell Scripts
 A shell script for an command named `extcmd` should be named `brew-extcmd`. This file will be run via `exec` with some Homebrew variables set as environmental variables, and passed any additional command-line arguments.
 
-<table>
-  <tr>
-    <td><strong>Variable</strong></td>
-    <td><strong>Description</strong></td>
-	</tr>
-  <tr>
-    <td>HOMEBREW_CACHE</td>
-		<td>Where Homebrew caches downloaded tarballs to, by default <code>~/Library/Caches/Homebrew</code>. </td>
-	</tr>
-  <tr>
-    <td>HOMEBREW_CELLAR</td>
-		<td>The location of the Homebrew Cellar, where software is staged. This will be <code>$HOMEBREW_PREFIX/Cellar</code> if that directory exists, or <code>$HOMEBREW_REPOSITORY/Cellar</code> otherwise.</td>
-  </tr>
-  <tr>
-    <td>HOMEBREW_LIBRARY_PATH</td>
-		<td>The directory containing Homebrew’s own application code.</td>
-	</tr>
-  <tr>
-    <td>HOMEBREW_PREFIX</td>
-		<td>Where Homebrew installs software. This is always the grandparent directory of the `brew` executable, <code>/usr/local</code> by default.</td>
-	</tr>
-  <tr>
-    <td>HOMEBREW_REPOSITORY</td>
-		<td>If installed from a Git clone, the repo directory (i.e., where Homebrew’s <code>.git</code> directory lives).</td>
-  </tr>
-</table>
+| Variable              | Description                                                                                                                                                             |
+|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| HOMEBREW_CACHE        | Where Homebrew caches downloaded tarballs to, by default ~/Library/Caches/Homebrew.                                                                                     |
+| HOMEBREW_CELLAR       | The location of the Homebrew Cellar, where software is staged. This will be $HOMEBREW_PREFIX/Cellar if that directory exists, or $HOMEBREW_REPOSITORY/Cellar otherwise. |
+| HOMEBREW_LIBRARY_PATH | The directory containing Homebrew’s own application code.                                                                                                               |
+| HOMEBREW_PREFIX       | Where Homebrew installs software. This is always the grandparent directory of the `brew` executable, /usr/local by default.                                             |
+| HOMEBREW_REPOSITORY   | If installed from a Git clone, the repo directory (i.e., where Homebrew’s .git directory lives).                                                                        |
+
 
 Note that the script itself can use any suitable shebang (`#!`) line, so an external “shell script” can be written for sh, bash, Ruby, or anything else.
 
-## USER-SUBMITTED COMMANDS
+## User-submitted Commands
 These commands have been contributed by Homebrew users but are not included in the main Homebrew repository, nor are they installed by the installer script. You can install them manually, as outlined above.
 
->*NOTE:* They are largely untested, and as always, be careful about running untested code on your machine.
+Note they are largely untested, and as always, be careful about running untested code on your machine.
 
 ### brew-livecheck
-> Check if there is a new upstream version of a formula.
->
-> See the [`README`](https://github.com/youtux/homebrew-livecheck/blob/master/README.md) for more info and usage.
->
-> Install using:
-> ```
-> $ brew tap youtux/livecheck
-> ```
+Check if there is a new upstream version of a formula.
+See the [`README`](https://github.com/youtux/homebrew-livecheck/blob/master/README.md) for more info and usage.
+
+Install using:
+```sh
+brew tap youtux/livecheck
+```
 
 ### brew-gem
->Install any gem package into a self-contained Homebrew cellar location: <https://github.com/sportngin/brew-gem>
->
->*Note:* This can also be installed with `brew install brew-gem`.
+Install any gem package into a self-contained Homebrew cellar location: [https://github.com/sportngin/brew-gem](https://github.com/sportngin/brew-gem).
+
+Note this can also be installed with `brew install brew-gem`.
 
 ### brew-growl
->Get Growl notifications for Homebrew https://github.com/secondplanet/brew-growl
+Get Growl notifications for Homebrew https://github.com/secondplanet/brew-growl
 
 ### brew-services
->Simple support to start formulae using launchctl, has out of the box support for any formula which defines `startup_plist` (e.g. mysql, postgres, redis u.v.m.): [https://github.com/Homebrew/homebrew-services](https://github.com/Homebrew/homebrew-services)
-
-> Install using:
-> ```
-  $ brew tap homebrew/services
-> ```
+Simple support to start formulae using launchctl, has out of the box support for any formula which defines `startup_plist` (e.g. mysql, postgres, redis u.v.m.): [https://github.com/Homebrew/homebrew-services](https://github.com/Homebrew/homebrew-services)
 
-## SEE ALSO
-Homebrew Docs: <https://github.com/Homebrew/brew/tree/master/docs>
+Install using:
+```sh
+brew tap homebrew/services
+```