Merge pull request #372 from dunglas/proselint

dunglas · web-flow · commit 03c62cb107e0 · 2017-12-28T16:50:38.000+01:00
Run Proselint in the CI and fix some errors
diff --git a/.proselintrc b/.proselintrc
@@ -0,0 +1,7 @@
+{
+  "checks": {
+    "typography.symbols": false,
+    "typography.exclamation": false,
+    "cliches.misc": false
+  }
+}
diff --git a/.travis.yml b/.travis.yml
@@ -8,13 +8,17 @@ env:
     secure: gjiWHIgNjLXuEFmLiepiOTHOuauHfeKHutrE0sBwFZUQzP9FoGTZzJub1z8/vm+hhygA+TZbB0iclygHyNrXCkZyNdnZXChXl4iPdYqY3OARPOAbQff16+/XSUDsZ/Ok1etdb3kKor1R4rBt/WywBvXmmdggumTA3yT5ExI+dyomdONo4yMUZ7g1la0ehMEzGqyVjt0nUW31PN3l6dI1qgigHCuotSrrpWP6fTXuUh5l6YA7KXb/V1hJxaGENLz1Cdfk0sF66e4KsV/DX6JZSqpvdqVB8OTPU+si511yJtGS8OeuLs4RqmXMLrY/ChCodlYnfCE+NleBFpUnCVqth/RDRh7LvplUJlpsXNcfyoA3mOFmZa0euOMCqJ3qwESz802Y9c5oN63hn2OUF/raFDc3SMMC86FFHxwyYjz5+yzXYupnFNj39NKdQ1v1KBbY8BD8UT8RU3mlu4/3LRz0tSamREHj3pGgBmvgUZfUE1dMngeaZjOmBaIZH8TnKQ75CvfnoT+LJnZo6g9g4uwz6jtaIziSMZ0OW/95nF8yx+xONbHEtt5ex5M09NOFsN2vB2bcUAgIjyGrmmNLQadwJyQv557IGPEE5CyGhJpXh9XZ+WMw2vO45MOw4sQPkARF6OJkMteqFc2NLXMOQJ07EScbgEKR/9VOcyxIk/7a7nc=
 
 install:
+  - pip install --user proselint
+  - cp .proselintrc ~
   - cd ..
   - git clone https://github.com/api-platform/website.git
   - cd website
   - yarn install
   - ln -s $TRAVIS_BUILD_DIR src/pages/docs
+  - cd $TRAVIS_BUILD_DIR
 
 script:
+  - find . -name '*.md' ! -name 'conduct.md' ! -name 'heroku.md' -exec proselint {} \;
   - cd $TRAVIS_BUILD_DIR/../website
   - bin/generate-nav
   - yarn gatsby build
diff --git a/admin/handling-relations-to-collections.md b/admin/handling-relations-to-collections.md
@@ -3,7 +3,7 @@
 Currently, API Platform Admin doesn't handle `to-many` relations. The core library [is being patched](https://github.com/api-platform/core/pull/1189)
 to document relations to collections through OWL.
 
-In the meantime, it is possible to manually configure API Platform to handle relations to collections.
+Meanwhile, it is possible to manually configure API Platform to handle relations to collections.
 
 We will create the admin for an API exposing `Person` and `Book` resources linked with a `many-to-many`
 relation between them (trough the `authors` property).
diff --git a/admin/index.md b/admin/index.md
@@ -1,6 +1,6 @@
 # The API Platform Admin
 
-API Platform Admin is a tool to automatically create a fancy (Material Design) and fully-featured administration interface
+API Platform Admin is a tool to automatically create a fancy (Material Design) and fully featured administration interface
 for any API supporting [the Hydra Core Vocabulary](http://www.hydra-cg.com/), including but not limited to all APIs created
 using [the API Platform framework](https://api-platform.com).
 
diff --git a/client-generator/troubleshooting.md b/client-generator/troubleshooting.md
@@ -14,10 +14,10 @@ specified the documentation URL instead of the entrypoint. For example if you ar
 documentation URL is at [https://demo.api-platform.com/docs](https://demo.api-platform.com/docs) the entry point is
 likely at [https://demo.api-platform.com](https://demo.api-platform.com). You can see an example of the expected
 response from an entrypoint in your browser by clicking visiting
-[https://demo.api-platform.com/index.jsonld](https://demo.api-platform.com/index.jsonld).   
+[https://demo.api-platform.com/index.jsonld](https://demo.api-platform.com/index.jsonld).
 
 * If you receive `TypeError: Cannot read property '@type' of undefined` or `TypeError: Cannot read property '0'
-of undefined` check that the URL you specified is accessible and returns jsonld.  You can check from the command line
+of undefined` check that the URL you specified is accessible and returns jsonld. You can check from the command line
 you are using by running something like `curl https://demo.api-platform.com/`.
 
 * If you receive a message like this:
diff --git a/core/content-negotiation.md b/core/content-negotiation.md
@@ -24,17 +24,14 @@ JSON                                                            | `json`       |
 XML                                                             | `xml`        | `application/xml`, `text/xml` | no
 HTML (API docs)                                                 | `html`       | `text/html`                   | no
 
-
 If the client requested format is not specified (if it's not supported, it will throw an HTTP bad format error), the response format will be the first format defined in the `formats` configuration key (see below).
 An example using the builtin XML support is available in [Behat specs](https://github.com/api-platform/core/blob/master/features/main/content_negotiation.feature).
 
-
-The API Platform content negotiation system is extensible. Support for other formats (such as [JSONAPI](http://jsonapi.org/))
+The API Platform content negotiation system is extendable. Support for other formats (such as [JSONAPI](http://jsonapi.org/))
 can be added by [creating and registering appropriate encoders and, sometimes, normalizers](https://symfony.com/doc/current/serializer.html#adding-normalizers-and-encoders). Adding support for other
-standard hypermedia formats upstream is very welcome. Don't hesitate to contribute by adding your encoders and normalizers
+standard hypermedia formats upstream is welcome. Don't hesitate to contribute by adding your encoders and normalizers
 to API Platform Core.
 
-
 ## Enabling Several Formats
 
 The first required step is to configure allowed formats. The following configuration will enable the support of XML (built-in)
@@ -68,13 +65,11 @@ API Platform Core will automatically call the serializer with your defined forma
 as `format` parameter during the deserialization process. Then it will return the result to the client with the asked MIME
 type using its built-in responder.
 
-
 ## Writing a Custom Normalizer
 
 Using composition is the recommended way to implement a custom normalizer. You can use the following template to start with your
 own implementation of `CustomItemNormalizer`:
 
-
 ```yaml
 # app/config/services.yml
 services:
diff --git a/core/data-providers.md b/core/data-providers.md
@@ -5,7 +5,7 @@ ORM](http://www.doctrine-project.org/projects/orm.html) to retrieve data from a
 is enabled by default. This data provider natively supports paged collections and filters. It can be used as is and fits
 perfectly with common usages.
 
-But sometime, you want to retrieve data from other sources such as another persistence layer, a webservice, ElasticSearch
+However, you sometime want to retrieve data from other sources such as another persistence layer, a webservice, ElasticSearch
 or MongoDB.
 Custom data providers can be used to do so. A project can include as many data providers as it needs. The first able to
 retrieve data for a given resource will be used.
diff --git a/core/events.md b/core/events.md
@@ -9,7 +9,7 @@ of event listeners are executed which validate the data, persist it in database,
 and create an HTTP response that will be sent to the client.
 
 To do so, API Platform Core leverages [events triggered by the Symfony HTTP Kernel](https://symfony.com/doc/current/reference/events.html#kernel-events).
-You can also hook your own code to those events. They are very handy and powerful extension points available at all points
+You can also hook your own code to those events. They are handy and powerful extension points available at all points
 of the request lifecycle.
 
 In the following example, we will send a mail each time a new book is created using the API:
diff --git a/core/form-data.md b/core/form-data.md
@@ -1,7 +1,7 @@
 # Accept `application/x-www-form-urlencoded` Form Data
 
 API Platform only supports raw documents as request input (encoded in JSON, XML, YAML...). This has many advantages including support of types and the ability to send back to the API documents originally retrieved through a `GET` request.
-But sometimes - for instance, to support legacy clients - it is necessary to accept inputs encoded in the traditional [`application/x-www-form-urlencoded`](https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1) format (HTML form content type). This can easily be done using [the powerful event system](events.md) of the framework.
+However, sometimes - for instance, to support legacy clients - it is necessary to accept inputs encoded in the traditional [`application/x-www-form-urlencoded`](https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1) format (HTML form content type). This can easily be done using [the powerful event system](events.md) of the framework.
 
 In this tutorial, we will decorate the default `DeserializeListener` class to handle form data if applicable, and delegate to the built-in listener for other cases.
 
diff --git a/core/fosuser-bundle.md b/core/fosuser-bundle.md
@@ -3,7 +3,7 @@
 API Platform Core is shipped with a bridge for [FOSUserBundle](https://github.com/FriendsOfSymfony/FOSUserBundle).
 If the FOSUser bundle is enabled, this bridge will use its `UserManager` to create, update and delete user resources.
 
-Note: FOSUserBundle is not very well suited for APIs. We strongly encourage you to use the [Doctrine user provider](https://symfony.com/doc/current/security/entity_provider.html)
+Note: FOSUserBundle is not well suited for APIs. We strongly encourage you to use the [Doctrine user provider](https://symfony.com/doc/current/security/entity_provider.html)
 shipped with Symfony or to [create a custom user provider](http://symfony.com/doc/current/security/custom_provider.html)
 instead of using this bundle.
 
diff --git a/core/index.md b/core/index.md
@@ -7,8 +7,8 @@ framework](https://symfony.com) (recommended).
 It embraces [JSON for Linked Data (JSON-LD)](http://json-ld.org) and [Hydra Core Vocabulary](http://www.hydra-cg.com) web
 standards but also supports [HAL](http://stateless.co/hal_specification.html), [Swagger/Open API](https://www.openapis.org/), XML, JSON, CSV and YAML.
 
-Build a working and fully-featured CRUD API in minutes. Leverage the awesome features of the tool to develop complex and
-high performance API-first projects.
+Build a working and fully featured CRUD API in minutes. Leverage the awesome features of the tool to develop complex and
+high performance API first projects.
 
 If you are starting a new project, the easiest way to get API Platform up is to install
 the [API Platform Distribution](../distribution/index.md).
@@ -17,7 +17,7 @@ the [API Platform Distribution](../distribution/index.md).
 
 ## Features
 
-Here is the fully-featured REST API you'll get in minutes:
+Here is the fully featured REST API you'll get in minutes:
 
 * [Automatic CRUD](operations.md)
 * Hypermedia (JSON-LD and HAL)
diff --git a/core/serialization.md b/core/serialization.md
@@ -13,7 +13,7 @@ The main serialization process has two stages:
 
 Unlike Symfony itself, API Platform leverages custom normalizers, its router and the [data provider](data-providers.md) system to do an advanced tranformation. Metadata are added to the generated document including links, type information, pagination data or available filters.
 
-The API Platform Serializer is very extensible, you can register custom normalizers and encoders to support other formats. You can also decorate existing normalizers to customize their behaviors.
+The API Platform Serializer is extendable, you can register custom normalizers and encoders to support other formats. You can also decorate existing normalizers to customize their behaviors.
 
 ## Available Serializers
 
diff --git a/deployment/heroku.md b/deployment/heroku.md
@@ -2,11 +2,11 @@
 
 [Heroku](http://heroku.com) is a popular, fast, scalable and reliable *Platform As A Service* (PaaS). As Heroku offers a
 free plan including database support through [Heroku Postgres](https://www.heroku.com/postgres), it's
-a very convenient way to experiment with the API Platform.
+a convenient way to experiment with the API Platform.
 
 The API Platform Heroku integration also supports MySQL databases provided by [the ClearDB add-on](https://addons.heroku.com/cleardb).
 
-Deploying API Platform applications on Heroku is very straightforward and you will learn how to do it in this tutorial.
+Deploying API Platform applications on Heroku is straightforward and you will learn how to do it in this tutorial.
 
 *Note: this tutorial works perfectly well with API Platform but also with any Symfony application based on the Symfony Standard
 Edition.*
diff --git a/distribution/index.md b/distribution/index.md
@@ -31,7 +31,7 @@ One more thing, before we start: API Platform is built on top of [the Symfony fr
 is compatible with most [Symfony bundles](https://symfony.com/blog/the-30-most-useful-symfony-bundles-and-making-them-even-better)
 (plugins) and benefits from the numerous extensions points provided by this rock-solid foundation (events, DIC...).
 Adding features like custom, service-oriented, API endpoints, JWT or OAuth authentication, HTTP caching, mail sending or
-asynchronous jobs to your APIs is very straightforward.
+asynchronous jobs to your APIs is straightforward.
 
 ## Installing the framework
 
@@ -134,14 +134,14 @@ to retrieve data in raw JSON.
 
 Of course, you can also use your favorite HTTP client to query the API. We strongly recommend to use [Postman](https://www.getpostman.com/).
 It works perfectly well with API Platform, also has native Swagger support, allows to easily write functional tests and
-has very good team collaboration features.
+has good team collaboration features.
 
 ## Creating the model
 
 API Platform is now 100% functional. Let's create our own data model.
 Our bookshop API will start simple. It will be composed of a `Book` resource type and a `Review` one.
 
-Books have an id, an ISBN number, a title, a description, an author, a publication date and are related to a list of reviews.
+Books have an id, an ISBN, a title, a description, an author, a publication date and are related to a list of reviews.
 Reviews have an id, a rating (between 0 and 5), a body, an author, a publication date and are related to one book.
 
 Let's describe this data model as a set of Plain Old PHP Objects (POPO) and map it to database's tables using annotations
@@ -173,7 +173,7 @@ class Book
     private $id;
 
     /**
-     * @var string|null The ISBN number of this book (or null if doesn't have one).
+     * @var string|null The ISBN of this book (or null if doesn't have one).
      *
      * @ORM\Column(nullable=true)
      */
@@ -373,7 +373,7 @@ in [adding some filters and adding sorts to the collection](../core/filters.md)
 You may have noticed that some keys start with the `@` symbol in the generated JSON response (`@id`, `@type`, `@context`...)?
 API Platform comes with a full support of the [JSON-LD](http://json-ld.org/) format (and its [Hydra](http://www.hydra-cg.com/)
 extension). It allows to build smart clients, with auto-discoverability capabilities (take a look at [Hydra console](http://www.markus-lanthaler.com/hydra/console/))
-and is very useful for open data, SEO and interoperability when [used with open vocabularies such as Schema.org](http://blog.schema.org/2013/06/schemaorg-and-json-ld.html).
+and is useful for open data, SEO and interoperability when [used with open vocabularies such as Schema.org](http://blog.schema.org/2013/06/schemaorg-and-json-ld.html).
 JSON-LD enables a lot of awesome advanced features (like [giving access to Google to your structured data](https://developers.google.com/search/docs/guides/intro-structured-data)
 or consuming APIs with [Apache Jena](https://jena.apache.org/documentation/io/#formats)).
 We think that it's the best default format for a new API. However, API Platform natively [supports many other formats](../core/content-negotiation.md)
@@ -437,7 +437,7 @@ Oops, we missed to add the title. But submit the request anyway. You should get
 
 Did you notice that the error was automatically serialized in JSON-LD and respect the Hydra Core vocabulary for errors?
 It allows the client to easily extract useful information from the error. Anyway, it's bad to get a SQL error when submitting
-a request. It means that we didn't use a valid input, and [it's a very bad and dangerous practice](https://www.owasp.org/index.php/Input_Validation_Cheat_Sheet).
+a request. It means that we didn't use a valid input, and [it's a bad and dangerous practice](https://www.owasp.org/index.php/Input_Validation_Cheat_Sheet).
 
 API Platform comes with a bridge with [the Symfony Validator Component](http://symfony.com/doc/current/validation.html).
 Adding some of [its numerous validation constraints](http://symfony.com/doc/current/validation.html#supported-constraints)
@@ -472,7 +472,7 @@ class Book
     private $id;
 
     /**
-     * @var string|null The ISBN number of this book (or null if doesn't have one).
+     * @var string|null The ISBN of this book (or null if doesn't have one).
      *
      * @ORM\Column(nullable=true)
      * @Assert\Isbn
@@ -601,9 +601,9 @@ prefer), try again the previous `POST` request.
 
 You now get proper validation error messages, always serialized using the Hydra error format (API Problem is also supported).
 Those errors are easy to parse client-side. By adding the proper validation constraints, we also noticed that the provided
-ISBN number isn't valid...
+ISBN isn't valid...
 
-Here we are! We have created a working and very powerful hypermedia REST API in a few minutes, and by writing only a few
+Here we are! We have created a working and powerful hypermedia REST API in a few minutes, and by writing only a few
 lines of PHP. But we only covered the basics.
 
 ## Going Client-Side
@@ -618,7 +618,7 @@ They are many more features to learn! Read [the full documentation](../core/inde
 to extend API Platform to fit your needs.
 API Platform is incredibly efficient for prototyping and Rapid Application Development (RAD). But the framework is also
 designed to create complex web APIs far beyond simple CRUD apps. It benefits from **strong extension points** and is **is
-continuously optimized for performance.** It powers very high-traffic websites.
+continuously optimized for performance.** It powers high-traffic websites.
 
 API Platform has a builtin HTTP cache invalidation system which allows to make API Platform apps blazing fast, and it uses
 [Varnish](https://varnish-cache.org/) by default. Read more in the chapter
diff --git a/extra/philosophy.md b/extra/philosophy.md
@@ -15,7 +15,7 @@ In 20 years of PHP, the web changed dramatically and is now evolving faster than
 to improve and professionalize the PHP ecosystem. The PHP world has closed the gap with most backend solutions and is often
 more innovative than them.
 
-But in critical area I've described previously, many things can be improved. Almost all existing solutions are still [designed
+However in critical area I've described previously, many things can be improved. Almost all existing solutions are still [designed
 and documented](https://symfony.com/doc/current/book/page_creation.html) to create websites the old way: a server generates
 then sends plain-old HTML documents to browsers.
 
diff --git a/index.md b/index.md
@@ -112,7 +112,7 @@
 2.  [Getting Started](schema-generator/getting-started.md)
 3.  [Configuration](schema-generator/configuration.md)
 
-## The Admin Component: Create a Fancy and Fully-Featured Administration Interface
+## The Admin Component: Create a Fancy and Fully Featured Administration Interface
 
 1.  [Introduction](admin/index.md)
     1.  [Features](admin/index.md#features)
diff --git a/schema-generator/index.md b/schema-generator/index.md
@@ -20,7 +20,7 @@ support.
 
 Bonus:
 
-* The code generator is fully configurable and extensible: all features can be deactivated (e.g.: the Doctrine mapping generator)
+* The code generator is fully configurable and extendable: all features can be deactivated (e.g.: the Doctrine mapping generator)
 and custom generator can be added (e.g.: a Doctrine ODM mapping generator).
 * The generated code can be used as is in a [Symfony](http://symfony.com) app (but it will work too in a raw PHP project
 or any other framework including [Laravel](http://laravel.com) and [Zend Framework](http://framework.zend.com/)).
