Add linting for our documentation and fix existing errors.

square · Jul 24, 2019 · b9b6509 · b9b6509
1 parent e3b3374
commit b9b6509
Show file tree

Hide file tree

Showing 16 changed files with 415 additions and 202 deletions.
diff --git a/.markdownlint.rb b/.markdownlint.rb
@@ -0,0 +1,45 @@
+#
+# Copyright 2019 Square Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# Configuring rules:
+# https://github.com/markdownlint/markdownlint/blob/master/docs/creating_styles.md
+# Rule list:
+# https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
+
+# Need to explicitly run all rules, so the per-rule configs below aren't used as an allowlist.
+all
+
+# Increase default line length from 80 to 100.
+rule 'MD013', :line_length => 100, :code_blocks => false, :tables => false
+
+# Enable inline HTML.
+exclude_rule 'MD033'
+
+# Allow paragraphs that consiste entirely of emphasized text.
+exclude_rule 'MD036'
+
+# Allow trailing question marks in headers.
+rule 'MD026', :punctuation => '.,;:!'
+
+# Markdownlint can't handle mkdocs' code block tab syntax, so disable code block formatting.
+exclude_rule 'MD040'
+exclude_rule 'MD046'
+
+# Don't care about blank lines surround fenced code blocks.
+exclude_rule 'MD031'
+
+# Allow raw URLs.
+exclude_rule 'MD034'
diff --git a/.travis.yml b/.travis.yml
@@ -17,6 +17,12 @@ matrix:
         - pip install mkdocs-material
       script:
         - mkdocs build
+    # Ensure docs are formatted correctly.
+    - language: ruby
+      install:
+        - gem install mdl
+      script:
+        - ./lint_docs.sh
     - language: android
       name: "Android"
       jdk: oraclejdk8

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -3,7 +3,7 @@ Open Source Code of Conduct
 
 At Square, we are committed to contributing to the open source community and simplifying the process
 of releasing and managing open source software. We’ve seen incredible support and enthusiasm from
-thousands of people who have already contributed to our projects — and we want to ensure our community
+thousands of people who have already contributed to our projects — and we want to ensure ourcommunity
 continues to be truly open for everyone.
 
 This code of conduct outlines our expectations for participants, as well as steps to reporting
@@ -12,28 +12,28 @@ expect our code of conduct to be honored.
 
 Square’s open source community strives to:
 
- * **Be open**: We invite anyone to participate in any aspect of our projects. Our community is
-   open, and any responsibility can be carried by a contributor who demonstrates the required
-   capacity and competence.
+* **Be open**: We invite anyone to participate in any aspect of our projects. Our community is
+  open, and any responsibility can be carried by a contributor who demonstrates the required
+  capacity and competence.
 
- * **Be considerate**: People use our work, and we depend on the work of others. Consider users and
-   colleagues before taking action. For example, changes to code, infrastructure, policy, and
-   documentation may negatively impact others.
+* **Be considerate**: People use our work, and we depend on the work of others. Consider users and
+  colleagues before taking action. For example, changes to code, infrastructure, policy, and
+  documentation may negatively impact others.
 
- * **Be respectful**: We expect people to work together to resolve conflict, assume good intentions,
-   and act with empathy. Do not turn disagreements into personal attacks.
+* **Be respectful**: We expect people to work together to resolve conflict, assume good intentions,
+  and act with empathy. Do not turn disagreements into personal attacks.
 
- * **Be collaborative**: Collaboration reduces redundancy and improves the quality of our work. We
-   strive for transparency within our open source community, and we work closely with upstream
-   developers and others in the free software community to coordinate our efforts.
+* **Be collaborative**: Collaboration reduces redundancy and improves the quality of our work. We
+  strive for transparency within our open source community, and we work closely with upstream
+  developers and others in the free software community to coordinate our efforts.
 
- * **Be pragmatic**: Questions are encouraged and should be asked early in the process to avoid
-   problems later. Be thoughtful and considerate when seeking out the appropriate forum for your
-   questions. Those who are asked should be responsive and helpful.
+* **Be pragmatic**: Questions are encouraged and should be asked early in the process to avoid
+  problems later. Be thoughtful and considerate when seeking out the appropriate forum for your
+  questions. Those who are asked should be responsive and helpful.
 
- * **Step down considerately**: Members of every project come and go. When somebody leaves or
-   disengages from the project, they should make it known and take the proper steps to ensure that
-   others can pick up where they left off.
+* **Step down considerately**: Members of every project come and go. When somebody leaves or
+  disengages from the project, they should make it known and take the proper steps to ensure that
+  others can pick up where they left off.
 
 This code is not exhaustive or complete. It serves to distill our common understanding of a
 collaborative, shared environment, and goals. We expect it to be followed in spirit as much as in
@@ -78,12 +78,12 @@ discretion.
 
 In your report please include:
 
- * Your contact information.
- * Names (real, nicknames, or pseudonyms) of any individuals involved. If there are additional
-   witnesses, please include them as well.
- * Your account of what occurred, and if you believe the incident is ongoing. If there is a publicly
-   available record (e.g. a mailing list archive or a public IRC logger), please include a link.
- * Any additional information that may be helpful.
+* Your contact information.
+* Names (real, nicknames, or pseudonyms) of any individuals involved. If there are additional
+  witnesses, please include them as well.
+* Your account of what occurred, and if you believe the incident is ongoing. If there is a publicly
+  available record (e.g. a mailing list archive or a public IRC logger), please include a link.
+* Any additional information that may be helpful.
 
 After filing a report, a representative from the Square Code of Conduct committee will contact you
 personally. The committee will then review the incident, follow up with any additional questions,
@@ -93,7 +93,6 @@ Anyone asked to stop unacceptable behavior is expected to comply immediately. If
 engages in unacceptable behavior, the Square Code of Conduct committee may take any action they deem
 appropriate, up to and including a permanent ban from all of Square spaces without warning.
 
-
 [codeofconduct_at]: mailto:[email protected]
 [twitter_coc]: https://github.com/twitter/code-of-conduct/blob/master/code-of-conduct.md
 [ubuntu_coc]: https://ubuntu.com/community/code-of-conduct

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -12,6 +12,5 @@ we use [Square's code style definitions][2].
 Before your code can be accepted into the project you must also sign the
 [Individual Contributor License Agreement (CLA)][1].
 
-
  [1]: https://spreadsheets.google.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1
  [2]: https://github.com/square/java-code-styles
diff --git a/README.md b/README.md
@@ -4,14 +4,17 @@
 [![CocoaPods compatible](https://img.shields.io/cocoapods/v/Workflow.svg)](https://cocoapods.org/pods/Workflow)
 [![Maven Central](https://img.shields.io/maven-central/v/com.squareup.workflow/workflow-core-jvm.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.squareup.workflow%22)
 
-An architecture that allows composable state machines to drive UI navigation and content, where the state machines are cleanly separated from UI code.
+An architecture that allows composable state machines to drive UI navigation and content, where the
+ state machines are cleanly separated from UI code.
 
 _**This project is currently experimental and the API subject to breaking changes without notice.**
-Follow Square's engineering blog, [The Corner](https://developer.squareup.com/blog/), to see when this project becomes stable._
+Follow Square's engineering blog, [The Corner](https://developer.squareup.com/blog/), to see when
+this project becomes stable._
 
 Workflow is a library for making composable state machines, and UIs driven by those state machines.
 
-This project is under active development. The workflow code is being piloted in production apps. The view code is not (yet).
+This project is under active development. The workflow code is being piloted in production apps. The
+view code is not (yet).
 
 More documentation and samples will be coming soon!
 
@@ -21,7 +24,8 @@ More documentation and samples will be coming soon!
 
 [![CocoaPods compatible](https://img.shields.io/cocoapods/v/Workflow.svg)](https://cocoapods.org/pods/Workflow)
 
-If you use CocoaPods to manage your dependencies, simply add Workflow and WorkflowUI to your Podfile:
+If you use CocoaPods to manage your dependencies, simply add Workflow and WorkflowUI to your
+Podfile:
 
 ```ruby
 pod 'Workflow'
@@ -32,7 +36,8 @@ pod 'WorkflowUI'
 
 [![Maven Central](https://img.shields.io/maven-central/v/com.squareup.workflow/workflow-core-jvm.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.squareup.workflow%22)
 
-Artifacts are hosted on Maven Central. If you're using Gradle, ensure `mavenCentral()` appears in your `repositories` block, and then add dependencies on the following artifacts:
+Artifacts are hosted on Maven Central. If you're using Gradle, ensure `mavenCentral()` appears in
+your `repositories` block, and then add dependencies on the following artifacts:
 
 <table>
   <tr>
@@ -41,7 +46,8 @@ Artifacts are hosted on Maven Central. If you're using Gradle, ensure `mavenCent
   </tr>
   <tr>
     <td nowrap><code>com.squareup.workflow:workflow-core-jvm:x.y.z</code></td>
-    <td>You are writing a library module/project that uses Workflows, but you don't need to interact with the runtime from the outside.</td>
+    <td>You are writing a library module/project that uses Workflows, but you don't need to interact
+    with the runtime from the outside.</td>
   </tr>
   <tr>
     <td nowrap><code>com.squareup.workflow:workflow-rx2:x.y.z</code></td>
@@ -59,7 +65,8 @@ Artifacts are hosted on Maven Central. If you're using Gradle, ensure `mavenCent
 
 #### Lower-level Artifacts
 
-Most code shouldn't need to depend on these directly. They should generally only be used to build higher-level integrations with UI frameworks.
+Most code shouldn't need to depend on these directly. They should generally only be used to build
+higher-level integrations with UI frameworks.
 
 <table>
   <tr>
@@ -72,25 +79,32 @@ Most code shouldn't need to depend on these directly. They should generally only
   </tr>
   <tr>
     <td nowrap><code>com.squareup.workflow:workflow-ui-core-jvm:x.y.z</code></td>
-    <td>You are writing workflow-ui-android for another UI framework. Defines the core types used by that artifact.</td>
+    <td>You are writing workflow-ui-android for another UI framework. Defines the core types used by
+    that artifact.</td>
   </tr>
 </table>
 
 ## Resources
 
- * [SF Android GDG @ Square 2019 - Hello Workflow](https://www.youtube.com/watch?v=8PlYtfsgDKs) (live coding)
- * [Android Dialogs 5-part Coding Series](https://twitter.com/chiuki/status/1100810374410956800)
-   * [1](https://www.youtube.com/watch?v=JJ4-8AR5HhA), [2](https://www.youtube.com/watch?v=XB6frWBGvp0), [3](https://www.youtube.com/watch?v=NdFJMkT-t3c), [4](https://www.youtube.com/watch?v=aRxmyO6fwSs), [5](https://www.youtube.com/watch?v=aKaZa-1KN2M)
- * [Reactive Workflows a Year Later – Droidcon NYC 2018](https://www.youtube.com/watch?v=cw9ZF9-ilac)
- * [The Reactive Workflow Pattern – Fragmented Podcast](https://www.youtube.com/watch?v=mUBXgYnT7w0)
- * [The Reactive Workflow Pattern Update – Droidcon SF 2017](https://www.youtube.com/watch?v=mvBVkU2mCF4)
- * [The Rx Workflow Pattern – Droidcon NYC 2017](https://www.youtube.com/watch?v=KjoMnsc2lPo) ([slides](https://speakerdeck.com/rjrjr/reactive-workflows))
+* [SF Android GDG @ Square 2019 - Hello Workflow](https://www.youtube.com/watch?v=8PlYtfsgDKs)
+  (live coding)
+* [Android Dialogs 5-part Coding Series](https://twitter.com/chiuki/status/1100810374410956800)
+  * [1](https://www.youtube.com/watch?v=JJ4-8AR5HhA),
+    [2](https://www.youtube.com/watch?v=XB6frWBGvp0),
+    [3](https://www.youtube.com/watch?v=NdFJMkT-t3c),
+    [4](https://www.youtube.com/watch?v=aRxmyO6fwSs),
+    [5](https://www.youtube.com/watch?v=aKaZa-1KN2M)
+* [Reactive Workflows a Year Later – Droidcon NYC 2018](https://www.youtube.com/watch?v=cw9ZF9-ilac)
+* [The Reactive Workflow Pattern – Fragmented Podcast](https://www.youtube.com/watch?v=mUBXgYnT7w0)
+* [The Reactive Workflow Pattern Update – Droidcon SF 2017](https://www.youtube.com/watch?v=mvBVkU2mCF4)
+* [The Rx Workflow Pattern – Droidcon NYC 2017](https://www.youtube.com/watch?v=KjoMnsc2lPo)
+  ([slides](https://speakerdeck.com/rjrjr/reactive-workflows))
 
 ## Releasing and Deploying
 
 See [RELEASING.md](RELEASING.md).
 
-# License
+## License
 
 <pre>
 Copyright 2019 Square Inc.

diff --git a/RELEASING.md b/RELEASING.md
@@ -4,10 +4,13 @@
 
 ---
 
-***Before you begin:*** *Please make sure you are set up with [`pod trunk`](https://guides.cocoapods.org/making/getting-setup-with-trunk.html) and your CocoaPods account is a contributor to both the Workflow and WorkflowUI pods. If you need to be added as a contributor, please [open a ticket requesting access](https://github.com/square/workflow/issues/new), and assign it to @apgar or @timdonnelly.*
+***Before you begin:*** *Please make sure you are set up with 
+[`pod trunk`](https://guides.cocoapods.org/making/getting-setup-with-trunk.html) and your CocoaPods
+account is a contributor to both the Workflow and WorkflowUI pods. If you need to be added as a
+contributor, please [open a ticket requesting access](https://github.com/square/workflow/issues/new),
+and assign it to @apgar or @timdonnelly.*
 
 ---
-
 1. Merge an update of [the change log](CHANGELOG.md) with the changes since the last release.
 
 1. Make sure you're on the `master` branch (or fix branch, e.g. `v0.1-fixes`).
@@ -17,70 +20,71 @@
    (cd kotlin && ./gradlew build connectedCheck)
    ```
 
-2. In `kotlin/gradle.properties`, remove the `-SNAPSHOT` prefix from the `VERSION_NAME` property.
+1. In `kotlin/gradle.properties`, remove the `-SNAPSHOT` prefix from the `VERSION_NAME` property.
    E.g. `VERSION_NAME=0.1.0`
 
-3. Create a commit and tag the commit with the version number:
+1. Create a commit and tag the commit with the version number:
    ```bash
    git commit -am "Releasing v0.1.0."
    git tag v0.1.0
    ```
 
-4. Upload the kotlin artifacts:
+1. Upload the kotlin artifacts:
    ```bash
    (cd kotlin && ./gradlew clean build && ./gradlew uploadArchives --no-parallel --no-daemon)
    ```
 
-   Disabling parallelism and daemon sharing is required by the vanniktech maven publish plugin. Without those,
-   the artifacts will be split across multiple (invalid) staging repositories.
+   Disabling parallelism and daemon sharing is required by the vanniktech maven publish plugin.
+   Without those, the artifacts will be split across multiple (invalid) staging repositories.
 
-5. Publish to CocoaPods:
+1. Publish to CocoaPods:
     ```bash
     bundle exec pod trunk push Workflow.podspec
     bundle exec pod trunk push WorkflowUI.podspec
     ```
 
-6. Bump the version
-    - **Kotlin:** Update the `VERSION_NAME` property in `kotlin/gradle.properties` to the new snapshot 
-      version, e.g. `VERSION_NAME=0.2.0-SNAPSHOT`.
-    - **Swift:** Update `s.version` in `*.podspec` to the new version, e.g. `0.2.0`.
+1. Bump the version
+   - **Kotlin:** Update the `VERSION_NAME` property in `kotlin/gradle.properties` to the new
+     snapshot version, e.g. `VERSION_NAME=0.2.0-SNAPSHOT`.
+   - **Swift:** Update `s.version` in `*.podspec` to the new version, e.g. `0.2.0`.
 
-7. Commit the new snapshot version:
+1. Commit the new snapshot version:
    ```
    git commit -am "Finish releasing v0.1.0."
    ```
 
-8. Push your commits and tag:
+1. Push your commits and tag:
    ```
    git push origin master
    # or git push origin fix-branch
    git push origin v0.1.0
    ```
 
-9. Create the release on GitHub:
-     1. Go to the [Releases](https://github.com/square/workflow/releases) page for the GitHub project.
-     2. Click "Draft a new release".
-     3. Enter the tag name you just pushed.
-     4. Title the release with the same name as the tag.
-     5. Copy & paste the changelog entry for this release into the description.
-     6. If this is a pre-release version, check the pre-release box.
-     7. Hit "Publish release".
-
-10. If this was a fix release, merge changes to the master branch:
-    ```bash
-    git checkout master
-    git reset --hard origin/master
-    git merge --no-ff v0.1-fixes
-    # Resolve conflicts. Accept master's versions of gradle.properties and podspecs.
-    git push origin master
-    ```
+1. Create the release on GitHub:
+   1. Go to the [Releases](https://github.com/square/workflow/releases) page for the GitHub
+      project.
+   1. Click "Draft a new release".
+   1. Enter the tag name you just pushed.
+   1. Title the release with the same name as the tag.
+   1. Copy & paste the changelog entry for this release into the description.
+   1. If this is a pre-release version, check the pre-release box.
+   1. Hit "Publish release".
+
+1. If this was a fix release, merge changes to the master branch:
+   ```bash
+   git checkout master
+   git reset --hard origin/master
+   git merge --no-ff v0.1-fixes
+   # Resolve conflicts. Accept master's versions of gradle.properties and podspecs.
+   git push origin master
+   ```
 
-11. Publish the website:
-    ```bash
-    # If you haven't already installed mkdocs, run:
-    # pip install mkdocs mkdocs-material
-    ./deploy_website.sh
-    ```
+1. Publish the website:
+   ```bash
+   # If you haven't already installed mkdocs, run:
+   # pip install mkdocs mkdocs-material
+   ./deploy_website.sh
+   ```
 
 ---
 
@@ -98,8 +102,8 @@ To build and install the current version to your local Maven repository (`~/.m2`
 
 #### Configuration
 
-In order to deploy artifacts to a Maven repository, you'll need to set 4 properties in your
-private Gradle properties file (`~/.gradle/gradle.properties`):
+In order to deploy artifacts to a Maven repository, you'll need to set 4 properties in your private
+Gradle properties file (`~/.gradle/gradle.properties`):
 
 ```
 RELEASE_REPOSITORY_URL=<url of release repository>