docs: Apply bullet style changes from Prettier.

Signed-off-by: Anders Kaseorg <anders@zulip.com>
This commit is contained in:
Anders Kaseorg
2021-08-20 12:45:39 -07:00
committed by Anders Kaseorg
parent 6145fdf678
commit 915884bff7
93 changed files with 1667 additions and 1667 deletions

View File

@@ -26,10 +26,10 @@ the validation Zulip has today.
Our API documentation is defined by a few sets of files:
* The primary source of our API documentation is the Zulip server's
- The primary source of our API documentation is the Zulip server's
[OpenAPI description](../documentation/openapi.md) at
`zerver/openapi/zulip.yaml`.
* The documentation is written the same Markdown framework that powers
- The documentation is written the same Markdown framework that powers
our [user docs](../documentation/user.md), with some special
extensions for rendering nice code blocks and example
responses. Most API endpoints share a common template,
@@ -38,25 +38,25 @@ Our API documentation is defined by a few sets of files:
require special content, as well as pages that document general API
details rather than specific endpoints, live at
`templates/zerver/api/*.md`.
* We have an extensive set of tests designed to validate that the data
- We have an extensive set of tests designed to validate that the data
in the OpenAPI file matching the implementation. Specifically,
`zerver/tests/test_openapi.py` compares every endpoint's accepted
parameters in `views` code with those declared in `zulip.yaml`. And
the [backend test suite](../testing/testing-with-django.md) checks
that every API response served during our extensive backend test
suite matches one the declared OpenAPI schema for that endpoint.
* The text for the Python examples comes from a test suite for the
- The text for the Python examples comes from a test suite for the
Python API documentation (`zerver/openapi/python_examples.py`; run via
`tools/test-api`). The `generate_code_example` macro will magically
read content from that test suite and render it as the code example.
This structure ensures that Zulip's API documentation is robust to a
wide range of possible typos and other bugs in the API
documentation.
* The JavaScript examples are similarly generated and tested using
- The JavaScript examples are similarly generated and tested using
`zerver/openapi/javascript_examples.js`.
* The cURL examples are generated and tested using
- The cURL examples are generated and tested using
`zerver/openapi/curl_param_value_generators.py`.
* The REST API index
- The REST API index
(`templates/zerver/help/include/rest-endpoints.md`) in the broader
/api left sidebar (`templates/zerver/api/sidebar_index.md`).
@@ -77,10 +77,10 @@ We highly recommend looking at those resources while reading this page.
If you look at the documentation for existing endpoints, you'll notice
that a typical endpoint's documentation is divided into four sections:
* The top-level **Title and description**
* **Usage examples**
* **Arguments**
* **Responses**
- The top-level **Title and description**
- **Usage examples**
- **Arguments**
- **Responses**
The rest of this guide describes how each of these sections works.
@@ -171,9 +171,9 @@ substitute it in place of
`{generate_code_example(python)|/messages/render:post|example}`
wherever that string appears in the API documentation.
* Additional Python imports can be added using the custom
- Additional Python imports can be added using the custom
`x-python-examples-extra-imports` field in the OpenAPI definition.
* Endpoints that only administrators can use should be tagged with the
- Endpoints that only administrators can use should be tagged with the
custom `x-requires-administrator` field in the OpenAPI definition.
### Parameters
@@ -237,11 +237,11 @@ above.
declared using `REQ`.
You can check your formatting using these helpful tools.
* `tools/check-openapi` will verify the syntax of `zerver/openapi/zulip.yaml`.
* `tools/test-backend zerver/tests/test_openapi.py`; this test compares
- `tools/check-openapi` will verify the syntax of `zerver/openapi/zulip.yaml`.
- `tools/test-backend zerver/tests/test_openapi.py`; this test compares
your documentation against the code and can find many common
mistakes in how arguments are declared.
* `test-backend`: The full Zulip backend test suite will fail if
- `test-backend`: The full Zulip backend test suite will fail if
any actual API responses generated by the tests don't match your
defined OpenAPI schema. Use `test-backend --rerun` for a fast
edit/refresh cycle when debugging.
@@ -320,14 +320,14 @@ Given that our documentation is written in large part using the
OpenAPI format, why maintain a custom Markdown system for displaying
it? There's several major benefits to this system:
* It is extremely common for API documentation to become out of date
- It is extremely common for API documentation to become out of date
as an API evolves; this automated testing system helps make it
possible for Zulip to maintain accurate documentation without a lot
of manual management.
* Every Zulip server can host correct API documentation for its
- Every Zulip server can host correct API documentation for its
version, with the key variables (like the Zulip server URL) already
pre-substituted for the user.
* We're able to share implementation language and visual styling with
- We're able to share implementation language and visual styling with
our Help Center, which is especially useful for the extensive
non-REST API documentation pages (e.g. our bot framework).