Docs: Fix formatting for vocabularies.rst and types.rst to conform

to Plone core documentation guidelines (one sentence per line,
don't wrap lines).

docs/source/types.rst

@@ -26,17 +26,13 @@ To get the schema of a content type, access the ``/@types`` endpoint  with the n
 The content type schema uses the `JSON Schema <http://json-schema.org/>`_ format.
 The tagged values for the widgets are also exposed in the the "properties" attribute of the schema.
 
-For ``Choice`` fields, their vocabulary or source will be linked to in a
-``vocabulary`` or ``querysource`` property (one or the other, never both):
+For ``Choice`` fields, their vocabulary or source will be linked to in a ``vocabulary`` or ``querysource`` property (one or the other, never both):
 
 
-- If a ``querysource`` property is included, that field is backed by an
-  ``IQuerysource``. In that case, the source's terms can't be enumerated, and
-  the terms need to be **queried** by issuing a request to the linked endpoint
-  and including the user's search terms in the ``?query=`` parameter.
-- If a ``vocabulary`` property is included, the field is backed by a vocabulary
-  or another kind of iterable source. The terms can then be **enumerated** by
-  issuing a request to the linked endpoint.
+- If a ``querysource`` property is included, that field is backed by an ``IQuerysource``.
+  In that case, the source's terms can't be enumerated, and the terms need to be **queried** by issuing a request to the linked endpoint and including the user's search terms in the ``?query=`` parameter.
+- If a ``vocabulary`` property is included, the field is backed by a vocabulary or another kind of iterable source.
+  The terms can then be **enumerated** by issuing a request to the linked endpoint.
 
 See :ref:`vocabularies` for details on these endpoints.
 

docs/source/vocabularies.rst

@@ -10,71 +10,52 @@ Sources are a similar, but are a more generic and dynamic concept.
 Concepts
 --------
 
-**Vocabularies** contain a list of terms. These terms are usually tokenized,
-meaning that in addition to a term's value, it also has a ``token`` which is a
-machine-friendly identifier for the term (7bit ASCII).
+**Vocabularies** contain a list of terms.
+These terms are usually tokenized, meaning that in addition to a term's value, it also has a ``token`` which is a machine-friendly identifier for the term (7bit ASCII).
 
 .. note::
-    Since the underlying value of a term might not necessarily be serializable
-    (it could be an arbitrary Python object), ``plone.restapi`` only exposes and
-    accepts tokens, and will transparently convert between tokens and values during
-    serialization / deseralization. For this reason, the following endpoints only
-    support *tokenized* vocabularies / sources, and they don't expose the terms'
-    values.
-
-Terms can also have a ``title``, which is intended to be the user-facing label
-for the term. For vocabularies or sources whose terms are only tokenized, but
-not titled, ``plone.restapi`` will fall back to using the token as the term
-title.
-
-**Sources** are similar to vocabularies, but they tend to be more dynamic in
-nature, and are often used for larger sets of terms. They are also not
-registered with a global name like vocabularies, but are instead addressed via
-the field they are assigned to.
+    Since the underlying value of a term might not necessarily be serializable (it could be an arbitrary Python object), ``plone.restapi`` only exposes and accepts tokens, and will transparently convert between tokens and values during serialization / deseralization.
+    For this reason, the following endpoints only support *tokenized* vocabularies / sources, and they do not expose the terms' values.
+
+Terms can also have a ``title``, which is intended to be the user-facing label for the term.
+For vocabularies or sources whose terms are only tokenized, but not titled, ``plone.restapi`` will fall back to using the token as the term title.
+
+**Sources** are similar to vocabularies, but they tend to be more dynamic in nature, and are often used for larger sets of terms.
+They are also not registered with a global name like vocabularies, but are instead addressed via the field they are assigned to.
 
 **Query Sources** are sources that are capable of being queried / searched.
 The source will then return only the subset of terms that match the query.
 
-The use of such a source is usually a strong indication that no attempt should
-be made to enumerate the full set of terms, but instead the source should only
-be queried, by presenting the user with an autocomplete widget for example.
+The use of such a source is usually a strong indication that no attempt should be made to enumerate the full set of terms, but instead the source should only be queried, by presenting the user with an autocomplete widget for example.
 
-Both vocabularies and sources can be context-sensitive, meaning that they
-take the context into account and their contents may therefore change
-depending on the context they're invoked on.
+Both vocabularies and sources can be context-sensitive, meaning that they take the context into account and their contents may therefore change depending on the context they're invoked on.
 
-This section can only provide a basic overview of vocabularies and related
-concepts. For a more in-depth explanation please refer to the
-`Plone documentation <https://docs.plone.org/develop/plone/forms/vocabularies.html>`_.
+This section can only provide a basic overview of vocabularies and related concepts.
+For a more in-depth explanation please refer to the `Plone documentation <https://docs.plone.org/develop/plone/forms/vocabularies.html>`_.
 
 Endpoints overview
 ------------------
 
-In ``plone.restapi`` these three concepts are exposed through three separate
-endpoints (described in more detail below):
+In ``plone.restapi`` these three concepts are exposed through three separate endpoints (described in more detail below):
 
 - **@vocabularies**/(vocab_name)
 - **@sources**/(field_name)
 - **@querysources**/(field_name) **?query=** (search_query)
 
-While the ``@vocabularies`` and ``@sources`` endpoints allow *enumerate*
-terms (and optionally have terms filtered server-side), the ``@querysources``
-endpoint **only** allows for searching the respective source.
+While the ``@vocabularies`` and ``@sources`` endpoints allow to *enumerate* terms (and optionally have terms filtered server-side), the ``@querysources`` endpoint **only** allows for searching the respective source.
 
 
 List all vocabularies
 ---------------------
 
 .. http:get:: (context)/@vocabularies
 
-To retrieve a list of all the available vocabularies, send a ``GET`` request
-to the ``@vocabularies`` endpoint:
+To retrieve a list of all the available vocabularies, send a ``GET`` request to the ``@vocabularies`` endpoint:
 
 ..  http:example:: curl httpie python-requests
     :request: ../../src/plone/restapi/tests/http-examples/vocabularies.req
 
-The response will include a list with the URL (``@id``) and the names
-(``title``) of all the available vocabularies in Plone:
+The response will include a list with the URL (``@id``) and the names (``title``) of all the available vocabularies in Plone:
 
 .. literalinclude:: ../../src/plone/restapi/tests/http-examples/vocabularies.resp
    :language: http
@@ -85,21 +66,19 @@ Get a vocabulary
 
 .. http:get:: (context)/@vocabularies/(vocab_name)
 
-To enumerate the terms of a particular vocabulary, use the ``@vocabularies``
-endpoint with the name of the vocabulary, e.g.
-``/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes``.
+To enumerate the terms of a particular vocabulary, use the ``@vocabularies`` endpoint with the name of the vocabulary, e.g. ``/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes``.
 The endpoint can be used with the site root and content objects.
 
 ..  http:example:: curl httpie python-requests
     :request: ../../src/plone/restapi/tests/http-examples/vocabularies_get.req
 
-The server will respond with a list of terms. The title is purely for display
-purposes. The token is what should be sent to the server to address that term.
+The server will respond with a list of terms.
+The title is purely for display purposes.
+The token is what should be sent to the server to address that term.
 
 .. note::
-    Vocabulary terms will be **batched** if the size of the
-    resultset exceeds the batch size. See :doc:`/batching` for more
-    details on how to work with batched results.
+    Vocabulary terms will be **batched** if the size of the resultset exceeds the batch size.
+    See :doc:`/batching` for more details on how to work with batched results.
 
 .. literalinclude:: ../../src/plone/restapi/tests/http-examples/vocabularies_get.resp
    :language: http
@@ -141,13 +120,9 @@ Get a source
 
 .. http:get:: (context)/@sources/(field_name)
 
-To enumerate the terms of a field's source, use the ``@sources`` endpoint on
-a specific context, and pass the field name as a path parameter, e.g.
-``/plone/doc/@sources/some_field``.
+To enumerate the terms of a field's source, use the ``@sources`` endpoint on a specific context, and pass the field name as a path parameter, e.g. ``/plone/doc/@sources/some_field``.
 
-Because sources are inherently tied to a specific field, this endpoint can
-only be invoked on content objects, and the source is addressed via the
-field name its used for, instead of a global name (which sources don't have).
+Because sources are inherently tied to a specific field, this endpoint can only be invoked on content objects, and the source is addressed via the field name its used for, instead of a global name (which sources don't have).
 
 Otherwise the endpoint behaves the same as the ``@vocabularies`` endpoint.
 
@@ -156,51 +131,41 @@ Example:
 ..  http:example:: curl httpie python-requests
     :request: ../../src/plone/restapi/tests/http-examples/sources_get.req
 
-The server will respond with a list of terms. The title is purely for display
-purposes. The token is what should be sent to the server to address that term.
+The server will respond with a list of terms.
+The title is purely for display purposes.
+The token is what should be sent to the server to address that term.
 
 .. literalinclude:: ../../src/plone/restapi/tests/http-examples/sources_get.resp
    :language: http
 
 .. note::
-    Technically there can be sources that are not iterable (ones that only
-    implement ``ISource``, but not ``IIterableSource``). These cannot be
-    enumerated using the ``@sources`` endpoint, and it will respond with a
-    corresponding error.
+    Technically there can be sources that are not iterable (ones that only implement ``ISource``, but not ``IIterableSource``).
+    These cannot be enumerated using the ``@sources`` endpoint, and it will respond with a corresponding error.
 
 
 Querying a query source
 -----------------------
 
 .. http:get:: (context)/@querysources/(field_name)?query=(search_query)
 
-Query sources (sources implementing `IQuerySource`) can be queried using this
-endpoint, by passing the search term in the ``query`` parameter. This search
-term will be passed to the query source's ``search()`` method, and the
-source's results are returned.
+Query sources (sources implementing `IQuerySource`) can be queried using this endpoint, by passing the search term in the ``query`` parameter.
+This search term will be passed to the query source's ``search()`` method, and the source's results are returned.
 
 Example:
 
 ..  http:example:: curl httpie python-requests
     :request: ../../src/plone/restapi/tests/http-examples/querysources_get.req
 
-The server will respond with a list of terms. The title is purely for display
-purposes. The token is what should be sent to the server to address that term.
+The server will respond with a list of terms.
+The title is purely for display purposes.
+The token is what should be sent to the server to address that term.
 
 .. literalinclude:: ../../src/plone/restapi/tests/http-examples/querysources_get.resp
    :language: http
 
 .. note::
-    Even though technically sources that implement ``IQuerySource`` are required
-    to implement ``__iter__`` as well (when strictly following the interface
-    interitance hierarchy), they usually are used in Plone in situations where
-    their full contents shouldn't or can't be enumerated (imagine a source of
-    all users, backed by a large LDAP, for example).
-
-    For this reason, ``plone.restapi`` takes the stance that the ``IQuerySource``
-    interface is a strong indication that this source should **only** be queried,
-    and therefore doesn't support enumeration of terms via the ``@querysources``
-    endpoint.
-
-    *(If the source does actually implement IIterableSource in addition to
-    IQuerySource, it can still be enumerated via the @sources endpoint)*
+    Even though technically sources that implement ``IQuerySource`` are required to implement ``__iter__`` as well (when strictly following the interface interitance hierarchy), they usually are used in Plone in situations where their full contents shouldn't or can't be enumerated (imagine a source of all users, backed by a large LDAP, for example).
+
+    For this reason, ``plone.restapi`` takes the stance that the ``IQuerySource`` interface is a strong indication that this source should **only** be queried, and therefore doesn't support enumeration of terms via the ``@querysources`` endpoint.
+
+    *(If the source does actually implement IIterableSource in addition to IQuerySource, it can still be enumerated via the @sources endpoint)*