Set up pre-commit (#73)

Added here:

- .pre-commit-config.yaml
- docs/project/contribution_tools.md
- src/scripts/pre-commit-toc.js
- CONTRIBUTING.md
- proposals/* (just to switch TOC formats)

The rest consists of auto-generated fixes.

The switch from doctoc to markdown-toc is because doctoc wants to put a TOC in every file, whereas markdown-toc only does it if you have an insertion point.

Co-authored-by: Chandler Carruth <chandlerc@gmail.com>

.github/workflows/publish-docs.yaml

@@ -2,32 +2,32 @@ name: Publish Carbon Documentation
 on:
   push:
     branches:
-    - master
+      - master
 
 jobs:
   build:
     runs-on: [ubuntu-latest]
     steps:
-    - uses: actions/checkout@v2
-    - uses: GoogleCloudPlatform/github-actions/setup-gcloud@master
-      with:
-        version: '285.0.0'
-        project_id: ${{ secrets.GCP_PROJECT_ID }}
-        service_account_email: ${{ secrets.GCP_SA_EMAIL }}
-        service_account_key: ${{ secrets.GCP_SA_KEY }}
-        export_default_credentials: true
-    - uses: actions/setup-ruby@v1
-      with:
-        ruby-version: 2.6
-    - run: gcloud info
-    - name: Install bundler
-      run: gem install bundler
-      working-directory: src/jekyll
-    - name: Install jekyll and dependencies
-      run: bundle install --jobs 4 --retry 3
-      working-directory: src/jekyll
-    - name: Build HTML pages
-      run: make build
-      working-directory: src/jekyll
-    - name: Publish to www.carbon-lang.dev
-      run: gsutil cp -R src/jekyll/.gen-site/* gs://www.carbon-lang.dev/
+      - uses: actions/checkout@v2
+      - uses: GoogleCloudPlatform/github-actions/setup-gcloud@master
+        with:
+          version: '285.0.0'
+          project_id: ${{ secrets.GCP_PROJECT_ID }}
+          service_account_email: ${{ secrets.GCP_SA_EMAIL }}
+          service_account_key: ${{ secrets.GCP_SA_KEY }}
+          export_default_credentials: true
+      - uses: actions/setup-ruby@v1
+        with:
+          ruby-version: 2.6
+      - run: gcloud info
+      - name: Install bundler
+        run: gem install bundler
+        working-directory: src/jekyll
+      - name: Install jekyll and dependencies
+        run: bundle install --jobs 4 --retry 3
+        working-directory: src/jekyll
+      - name: Build HTML pages
+        run: make build
+        working-directory: src/jekyll
+      - name: Publish to www.carbon-lang.dev
+        run: gsutil cp -R src/jekyll/.gen-site/* gs://www.carbon-lang.dev/

.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.4.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-yaml
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: ['--fix=lf']
+      - id: trailing-whitespace
+  - repo: local
+    hooks:
+      - id: markdown-toc
+        name: markdown-toc
+        description: Runs https://github.com/jonschlinkert/markdown-toc
+        entry: src/scripts/pre-commit-toc.js
+        language: node
+        additional_dependencies: [markdown-toc]
+        files: .*\.md$
+        exclude: ^src/jekyll/theme/
+  # Prettier should be run late so that it can re-format any prior changes.
+  - repo: https://github.com/prettier/prettier
+    rev: 2.0.5
+    hooks:
+      - id: prettier
+        exclude: ^src/jekyll/theme/

CONTRIBUTING.md

@@ -184,6 +184,14 @@ follow the Carbon documentation and coding styles.
   - Keep in mind that code contribution guidelines are incomplete while we start
     work on Carbon, and may change later.
 
+## pre-commit
+
+We use [pre-commit](/docs/project/contribution_tools.md#pre-commit) for
+automated checks, including formatting of documentation. Please see
+[contribution tools](/docs/project/contribution_tools.md) for more information.
+
+Please use pre-commit to simplify reviews.
+
 ## Style
 
 ### Google Docs and Markdown
@@ -191,8 +199,8 @@ follow the Carbon documentation and coding styles.
 Changes to Carbon documentation follow the
 [Google developer documentation style guide](https://developers.google.com/style).
 
-Markdown files should additionally use [Prettier](https://prettier.io/) for
-formatting.
+Markdown files should additionally use
+[Prettier](/docs/project/contribution_tools.md#prettier) for formatting.
 
 Other style points to be aware of are:
 

docs/project/commenting_guidelines.md

@@ -25,7 +25,9 @@ always try to keep feedback, even when critical, constructive and supportive.
   - If your comment represents a significant change to the proposal, include a
     list of pros and cons. Even if the author disagrees with the change, they
     can use those to document the alternative.
-  - Feel free to extract long side discussions to a Discourse Forum topic, but make sure any important conclusions or outcomes are reflected in either the GitHub comments or the change itself.
+  - Feel free to extract long side discussions to a Discourse Forum topic, but
+    make sure any important conclusions or outcomes are reflected in either the
+    GitHub comments or the change itself.
 
 - **Be supportive in your criticism.** The author may be receiving many
   comments, and we want to keep contributors motivated to respond.

docs/project/contribution_tools.md

@@ -0,0 +1,64 @@
+# Contribution tools
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+The Carbon language project has a number of tools used to assist in preparing
+contributions.
+
+## Table of contents
+
+<!-- toc -->
+
+- [pre-commit](#pre-commit)
+- [markdown-toc](#markdown-toc)
+- [Prettier](#prettier)
+  - [vim-prettier](#vim-prettier)
+
+<!-- tocstop -->
+
+## pre-commit
+
+We use [pre-commit](https://pre-commit.com) to run
+[various checks](/.pre-commit-config.yaml). This will automatically run
+important checks, including formatting.
+
+To set up pre-commit:
+
+- Follow the [installation instructions](https://pre-commit.com/#installation).
+- Enable per-repo: `pre-commit install`
+
+When modifying or adding pre-commit hooks, please run
+`pre-commit run --all-files` to see what changes.
+
+## markdown-toc
+
+**pre-commit enabled**: markdown-toc will be run by pre-commit, if installed.
+
+We use [markdown-toc](https://github.com/jonschlinkert/markdown-toc) to provide
+GitHub-compatible tables of contents for some documents.
+
+If run manually, specify `--bullets=-` to use Prettier-compatible bullets, or
+always run Prettier after markdown-toc.
+
+## Prettier
+
+**pre-commit enabled**: Prettier will be run by pre-commit, if installed.
+
+We use [Prettier](https://prettier.io/) for formatting. There is an
+[rc file](/.prettierrc) for configuration.
+
+### vim-prettier
+
+If you use [vim-prettier](https://github.com/prettier/vim-prettier), it may help
+to add to your `.virmc`:
+
+```
+let g:prettier#config#print_width = '80'
+let g:prettier#config#tab_width = '2'
+let g:prettier#config#use_tabs = 'false'
+let g:prettier#config#prose_wrap = 'always'
+```

proposals/p0044.md

@@ -12,8 +12,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 ## Table of contents
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+<!-- toc -->
 
 - [Problem](#problem)
 - [Background](#background)
@@ -67,7 +66,7 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
     - [StackEdit](#stackedit)
   - [GitHub Markdown syntax highlighting](#github-markdown-syntax-highlighting)
 
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- tocstop -->
 
 ## Problem
 

proposals/template.md

@@ -12,9 +12,16 @@ SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 ## Table of contents
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+<!-- toc -->
+
+- [TODO: Initial proposal setup](#todo-initial-proposal-setup)
+- [Problem](#problem)
+- [Background](#background)
+- [Proposal](#proposal)
+- [Details](#details)
+- [Alternatives considered](#alternatives-considered)
+
+<!-- tocstop -->
 
 ## TODO: Initial proposal setup
 

src/scripts/pre-commit-toc.js

@@ -0,0 +1,28 @@
+#!/usr/local/bin/node
+
+/*
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+*/
+
+/*
+Runs markdown-toc for pre-commits. This is necessary to handle multiple file
+arguments, which markdown-toc does not.
+
+Humans should generally use markdown-toc following the install instructions
+from https://github.com/jonschlinkert/markdown-toc.
+*/
+
+const mdtoc = require('markdown-toc');
+const fs = require('fs');
+
+const files = process.argv.slice(2);
+for (var i = 0; i < files.length; ++i) {
+  const oldContent = fs.readFileSync(files[i]).toString();
+  const newContent = mdtoc.insert(oldContent, { bullets: '-' });
+  if (oldContent != newContent) {
+    console.log(`Updating ${files[i]}`);
+    fs.writeFileSync(files[i], newContent);
+  }
+}