mirror of
https://github.com/zulip/zulip.git
synced 2025-10-23 04:52:12 +00:00
docs: Apply bullet style changes from Prettier.
Signed-off-by: Anders Kaseorg <anders@zulip.com>
This commit is contained in:
committed by
Anders Kaseorg
parent
6145fdf678
commit
915884bff7
@@ -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).
|
||||
|
||||
|
Reference in New Issue
Block a user