paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-23 04:52:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Apply sentence single-spacing from Prettier.

Browse Source 
Signed-off-by: Anders Kaseorg <anders@zulip.com>
This commit is contained in:
Anders Kaseorg
2021-08-20 12:53:28 -07:00
committed by Anders Kaseorg
parent 915884bff7
commit 35c1c8d41b
105 changed files with 1525 additions and 1525 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/documentation/api.md
View File

@@ -4,7 +4,7 @@ This document explains the system for documenting [Zulip's REST
API](https://zulip.com/api/rest).
Zulip's API documentation is an essential resource both for users and
for the developers of Zulip's mobile and terminal apps. Our vision is
for the developers of Zulip's mobile and terminal apps. Our vision is
for the documentation to be sufficiently good that developers of
Zulip's apps should never need to look at the server's implementation
to answer questions about the API's semantics.
@@ -15,13 +15,13 @@ and remains so as Zulip's API evolves.
In particular, the top goal for this system is that all mistakes in
verifiable content (i.e. not the English explanations) should cause
the Zulip test suite to fail. This is incredibly important, because
the Zulip test suite to fail. This is incredibly important, because
once you notice one error in API documentation, you no longer trust it
to be correct, which ends up wasting the time of its users.
Since it's very difficult to not make little mistakes when writing any
untested code, the only good solution to this is a way to test
the documentation. We found dozens of errors in the process of adding
the documentation. We found dozens of errors in the process of adding
the validation Zulip has today.
Our API documentation is defined by a few sets of files:
@@ -41,13 +41,13 @@ Our API documentation is defined by a few sets of files:
- 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
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
Python API documentation (`zerver/openapi/python_examples.py`; run via
`tools/test-api`). The `generate_code_example` macro will magically
`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
@@ -99,11 +99,11 @@ relevant feature in `/help/`.
### Usage examples
We display usage examples in three languages: Python, JavaScript and
`curl`; we may add more in the future. Every endpoint should have
`curl`; we may add more in the future. Every endpoint should have
Python and `curl` documentation; `JavaScript` is optional as we don't
consider that API library to be fully supported. The examples are
consider that API library to be fully supported. The examples are
defined using a special Markdown extension
(`zerver/openapi/markdown_extension.py`). To use this extension, one
(`zerver/openapi/markdown_extension.py`). To use this extension, one
writes a Markdown file block that looks something like this:
```md
@@ -131,7 +131,7 @@ parameter.
For the Python examples, you'll write the example in
`zerver/openapi/python_examples.py`, and it'll be run and verified
automatically in Zulip's automated test suite. The code there will
automatically in Zulip's automated test suite. The code there will
look something like this:
``` python
@@ -149,14 +149,14 @@ def render_message(client: Client) -> None:
```
This is an actual Python function which will be run as part of the
`tools/test-api` test suite. The `validate_against_opanapi_schema`
`tools/test-api` test suite. The `validate_against_opanapi_schema`
function will verify that the result of that request is as defined in
the examples in `zerver/openapi/zulip.yaml`.
To run as part of the test suite, the `render_message` function needs
to be called from `test_messages` (or one of the other functions at
the bottom of the file). The final function, `test_the_api`, is what
actually runs the tests. Tests with the `openapi_test_function`
the bottom of the file). The final function, `test_the_api`, is what
actually runs the tests. Tests with the `openapi_test_function`
decorator that are not called will fail tests, as will new endpoints
that are not covered by an `openapi_test_function`-decorated test.
@@ -179,7 +179,7 @@ wherever that string appears in the API documentation.
### Parameters
We have a separate Markdown extension to document the parameters that
an API endpoint supports. You'll see this in files like
an API endpoint supports. You'll see this in files like
`templates/zerver/api/render-message.md` via the following Markdown
directive (implemented in
`zerver/lib/markdown/api_arguments_table_generator.py`):
@@ -215,17 +215,17 @@ in the OpenAPI definition.
## Step by step guide
This section offers a step-by-step process for adding documentation
for a new API endpoint. It assumes you've read and understood the
for a new API endpoint. It assumes you've read and understood the
above.
1. Start by adding [OpenAPI format](../documentation/openapi.md)
data to `zerver/openapi/zulip.yaml` for the endpoint. If you
data to `zerver/openapi/zulip.yaml` for the endpoint. If you
copy-paste (which is helpful to get the indentation structure
right), be sure to update all the content that you copied to
correctly describe your endpoint!
In order to do this, you need to figure out how the endpoint in
question works by reading the code! To understand how arguments
question works by reading the code! To understand how arguments
are specified in Zulip backend endpoints, read our [REST API
tutorial][rest-api-tutorial], paying special attention to the
details of `REQ` and `has_request_variables`.
@@ -243,7 +243,7 @@ above.
mistakes in how arguments are declared.
- `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
defined OpenAPI schema. Use `test-backend --rerun` for a fast
edit/refresh cycle when debugging.
[rest-api-tutorial]: ../tutorials/writing-views.html#writing-api-rest-endpoints
@@ -251,7 +251,7 @@ above.
1. Add a function for the endpoint you'd like to document to
`zerver/openapi/python_examples.py`, decorated with
`@openapi_test_function`. `render_message` is a good example to
follow. There are generally two key pieces to your test: (1) doing
follow. There are generally two key pieces to your test: (1) doing
an API query and (2) verifying its result has the expected format
using `validate_against_openapi_schema`.
@@ -270,11 +270,11 @@ above.
function will be called when running `test-api`.
1. Capture the JSON response returned by the API call (the test
"fixture"). The easiest way to do this is add an appropriate print
"fixture"). The easiest way to do this is add an appropriate print
statement (usually `json.dumps(result, indent=4, sort_keys=True)`),
and then run `tools/test-api`. You can also use
and then run `tools/test-api`. You can also use
<https://jsonformatter.curiousconcept.com/> to format the JSON
fixtures. Add the fixture to the `example` subsection of the
fixtures. Add the fixture to the `example` subsection of the
`responses` section for the endpoint in
`zerver/openapi/zulip.yaml`.
@@ -302,7 +302,7 @@ above.
1. Test your endpoint, pretending to be a new user in a hurry, by
visiting it via the links on `http://localhost:9991/api` (the API
docs are rendered from the Markdown source files on page load, so
just reload to see an updated version as you edit). You should
just reload to see an updated version as you edit). You should
make sure that copy-pasting the code in your examples works, and
post an example of the output in the pull request.
@@ -318,7 +318,7 @@ above.
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? There's several major benefits to this system:
- It is extremely common for API documentation to become out of date
as an API evolves; this automated testing system helps make it