docs: Apply bullet style changes from Prettier.

Signed-off-by: Anders Kaseorg <anders@zulip.com>
(cherry picked from commit 915884bff7)
This commit is contained in:
Anders Kaseorg
2021-08-20 12:45:39 -07:00
committed by Tim Abbott
parent 5ae8fe292d
commit 0147c6adce
94 changed files with 1674 additions and 1674 deletions

View File

@@ -26,30 +26,30 @@ the validation Zulip has today.
Our API documentation is defined by a few sets of files:
* Most data describing API endpoints and examples is stored in our
- Most data describing API endpoints and examples is stored in our
[OpenAPI configuration](../documentation/openapi.md) at
`zerver/openapi/zulip.yaml`.
* The top-level templates live under `templates/zerver/api/*`, and are
- The top-level templates live under `templates/zerver/api/*`, and are
written using the Markdown framework that powers our [user
docs](../documentation/user.md), with some special extensions for
rendering nice code blocks and example responses. We expect to
eventually remove most of these files where it is possible to
fully generate the documentation from the OpenAPI files.
* 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`).
* 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 this file is correct, `zerver/tests/test_openapi.py` compares
every endpoint's accepted parameters in `views` code with those
declared in `zulip.yaml`. And [backend test
@@ -74,10 +74,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 **Description**
* **Usage examples**
* **Arguments**
* **Responses**
- The top-level **Description**
- **Usage examples**
- **Arguments**
- **Responses**
The rest of this guide describes how each of these sections works.
@@ -215,11 +215,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.
@@ -293,14 +293,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).