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

docs: Apply bullet style changes from Prettier.

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/documentation/api.md
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).

30
docs/documentation/integrations.md
View File

@@ -10,14 +10,14 @@ integrations).
Usually, this involves a few steps:
* Add text explaining all of the steps required to set up the
- Add text explaining all of the steps required to set up the
integration, including what URLs to use, etc. See
[Writing guidelines](#writing-guidelines) for detailed writing guidelines.
Zulip's pre-defined Markdown macros can be used for some of these steps.
See [Markdown macros](#markdown-macros) for further details.
* Make sure you've added your integration to
- Make sure you've added your integration to
`zerver/lib/integrations.py` in both the `WEBHOOK_INTEGRATIONS`
section (or `INTEGRATIONS` if not a webhook), and the
`DOC_SCREENSHOT_CONFIG` sections. These registries configure your
@@ -26,7 +26,7 @@ Usually, this involves a few steps:
message (which is important for the screenshots to be updated as
Zulip's design changes).
* You'll need to add an SVG graphic
- You'll need to add an SVG graphic
of your integration's logo under the
`static/images/integrations/logos/<name>.svg`, where `<name>` is the
name of the integration, all in lower case; you can usually find them in the
@@ -40,7 +40,7 @@ Usually, this involves a few steps:
If you cannot find an SVG graphic of the logo, please find and include a PNG
image of the logo instead.
* Finally, generate a message sent by the integration and take a screenshot of
- Finally, generate a message sent by the integration and take a screenshot of
the message to provide an example message in the documentation.
If your new integration is an incoming webhook integration, you can generate
@@ -71,12 +71,12 @@ always create a new macro by adding a new file to that folder.
Here are a few common macros used to document Zulip's integrations:
* `{!create-stream.md!}` macro - Recommends that users create a dedicated
- `{!create-stream.md!}` macro - Recommends that users create a dedicated
stream for a given integration. Usually the first step is setting up an
integration or incoming webhook. For an example rendering, see **Step 1** of
[the docs for Zulip's GitHub integration][github-integration].
* `{!create-bot-construct-url-indented.md!}` macro - Instructs users to create a bot
- `{!create-bot-construct-url-indented.md!}` macro - Instructs users to create a bot
for a given integration and construct a webhook URL using the bot API key
and stream name. The URL is generated automatically for every incoming webhook
by using attributes in the `WebhookIntegration` class in
@@ -91,49 +91,49 @@ Here are a few common macros used to document Zulip's integrations:
deployed on. If special configuration is required to set the `SITE`
variable, you should document that too.
* `{!append-stream-name.md!}` macro - Recommends appending `&stream=stream_name`
- `{!append-stream-name.md!}` macro - Recommends appending `&stream=stream_name`
to a URL in cases where supplying a stream name in the URL is optional.
Supplying a stream name is optional for most Zulip integrations. If you use
`{!create-bot-construct-url-indented.md!}`, this macro need not be used.
* `{!append-topic.md!}` macro - Recommends appending `&topic=my_topic` to a URL
- `{!append-topic.md!}` macro - Recommends appending `&topic=my_topic` to a URL
to supply a custom topic for webhook notification messages. Supplying a custom
topic is optional for most Zulip integrations. If you use
`{!create-bot-construct-url-indented.md!}`, this macro need not be used.
* `{!congrats.md!}` macro - Inserts congratulatory lines signifying the
- `{!congrats.md!}` macro - Inserts congratulatory lines signifying the
successful setup of a given integration. This macro is usually used at
the end of the documentation, right before the sample message screenshot.
For an example rendering, see the end of
[the docs for Zulip's GitHub integration][github-integration].
* `{!download-python-bindings.md!}` macro - Links to Zulip's
- `{!download-python-bindings.md!}` macro - Links to Zulip's
[API page](https://zulip.com/api/) to download and install Zulip's
API bindings. This macro is usually used in non-webhook integration docs under
`templates/zerver/integrations/<integration_name>.md`. For an example
rendering, see **Step 2** of
[the docs for Zulip's Codebase integration][codebase].
* `{!change-zulip-config-file.md!}` macro - Instructs users to create a bot and
- `{!change-zulip-config-file.md!}` macro - Instructs users to create a bot and
specify said bot's credentials in the config file for a given non-webhook
integration. This macro is usually used in non-webhook integration docs under
`templates/zerver/integrations/<integration_name>.md`. For an example
rendering, see **Step 4** of
[the docs for Zulip's Codebase integration][codebase].
* `{!git-append-branches.md!}` and `{!git-webhook-url-with-branches.md!}` -
- `{!git-append-branches.md!}` and `{!git-webhook-url-with-branches.md!}` -
These two macros explain how to specify a list of branches in the webhook URL
to filter notifications in our Git-related webhooks. For an example rendering,
see the last paragraph of **Step 2** in
[the docs for Zulip's GitHub integration][github-integration].
* `{!webhook-url.md!}` - Used internally by `{!create-bot-construct-url-indented.md!}`
- `{!webhook-url.md!}` - Used internally by `{!create-bot-construct-url-indented.md!}`
to generate the webhook URL.
* `{!zulip-config.md!}` - Used internally by `{!change-zulip-config-file.md!}`
- `{!zulip-config.md!}` - Used internally by `{!change-zulip-config-file.md!}`
to specify the lines in the config file for a non-webhook integration.
* `{!webhook-url-with-bot-email.md!}` - Used in certain non-webhook integrations
- `{!webhook-url-with-bot-email.md!}` - Used in certain non-webhook integrations
to generate URLs of the form:
```text

8
docs/documentation/openapi.md
View File

@@ -144,7 +144,7 @@ You can find more examples, including GET requests and nested objects, in
We're collecting decisions we've made on how our Swagger YAML files
should be organized here:
* Use shared definitions and YAML anchors to avoid duplicating content
- Use shared definitions and YAML anchors to avoid duplicating content
where possible.
## Tips for working with YAML:
@@ -169,13 +169,13 @@ correct.
### Formatting help:
* Comments begin with a # character.
- Comments begin with a # character.
* Descriptions do not need to be in quotes, and may use common
- Descriptions do not need to be in quotes, and may use common
Markdown format options like inline code \` (backtick) and `#`
headings.
* A single `|` (pipe) character begins a multi-line description on the
- A single `|` (pipe) character begins a multi-line description on the
next line. Single spaced lines (one newline at the end of each) are
joined. Use an extra blank line for a paragraph break. We prefer
to use this format for all descriptions because it doesn't require

22
docs/documentation/overview.md
View File

@@ -2,26 +2,26 @@
Zulip has three major documentation systems:
* Developer and sysadmin documentation: Documentation for people
- Developer and sysadmin documentation: Documentation for people
actually interacting with the Zulip codebase (either by developing
it or installing it), and written in Markdown.
* Core website documentation: Complete webpages for complex topics,
- Core website documentation: Complete webpages for complex topics,
written in HTML, JavaScript, and CSS (using the Django templating
system). These roughly correspond to the documentation someone
might look at when deciding whether to use Zulip. We don't expect
to ever have more than about 10 pages written using this system.
* User-facing documentation: Our scalable system for documenting
- User-facing documentation: Our scalable system for documenting
Zulip's huge collection of specific features without a lot of
overhead or duplicated code/syntax, written in Markdown. We have
several hundred pages written using this system. There are 3
branches of this documentation:
* User documentation (with a target audience of individual Zulip
- User documentation (with a target audience of individual Zulip
users),
* Integrations documentation (with a target audience of IT folks
- Integrations documentation (with a target audience of IT folks
setting up integrations), and
* API documentation (with a target audience of developers writing
- API documentation (with a target audience of developers writing
code to extend Zulip).
These three systems are documented in detail.
@@ -131,12 +131,12 @@ details on how to contribute to this documentation.
Zulip has several automated test suites that we run in CI and
recommend running locally when making significant edits:
* `tools/lint` catches a number of common mistakes, and we highly
- `tools/lint` catches a number of common mistakes, and we highly
recommend
[using our linter pre-commit hook](../git/zulip-tools.html#set-up-git-repo-script).
See the [main linter doc](../testing/linters.md) for more details.
* The ReadTheDocs docs are built and the links tested by
- The ReadTheDocs docs are built and the links tested by
`tools/test-documentation`, which runs `build-docs` and then checks
all the links.
@@ -144,17 +144,17 @@ There's an exclude list for the link testing at this horrible path:
`tools/documentation_crawler/documentation_crawler/spiders/common/spiders.py`,
which is relevant for flaky links.
* The API docs are tested by `tools/test-api`, which does some basic
- The API docs are tested by `tools/test-api`, which does some basic
payload verification. Note that this test does not check for broken
links (those are checked by `test-help-documentation`).
* `tools/test-help-documentation` checks `/help/`, `/api/`,
- `tools/test-help-documentation` checks `/help/`, `/api/`,
`/integrations/`, and the core website ("portico") documentation for
broken links. Note that the "portico" documentation check has a
manually maintained whitelist of pages, so if you add a new page to
this site, you will need to edit `PorticoDocumentationSpider` to add it.
* `tools/test-backend test_docs.py` tests various internal details of
- `tools/test-backend test_docs.py` tests various internal details of
the variable substitution logic, as well as rendering. It's
essential when editing the documentation framework, but not
something you'll usually need to interact with when editing

82
docs/documentation/user.md
View File

@@ -8,12 +8,12 @@ There are two types of documents: articles about specific features, and a
handful of longer guides.
The feature articles serve a few different purposes:
* Feature discovery, for someone browsing the `/help` page, and looking at
- Feature discovery, for someone browsing the `/help` page, and looking at
the set of titles.
* Public documentation of our featureset, for someone googling "can zulip do .."
* Canned responses to support questions; if someone emails a Zulip admin
- Public documentation of our featureset, for someone googling "can zulip do .."
- Canned responses to support questions; if someone emails a Zulip admin
asking "how do I change my name", they can reply with a link to the doc.
* Feature explanations for new Zulip users and admins, especially for
- Feature explanations for new Zulip users and admins, especially for
organization settings.
This system is designed to make writing and maintaining such documentation
@@ -52,22 +52,22 @@ experience with.
Tips for adding a new article:
* Find an existing article in the same section of the help documentation,
- Find an existing article in the same section of the help documentation,
and copy the format, wording, style, etc as closely as you can.
* If the feature exists in other team chat products, check out their
- If the feature exists in other team chat products, check out their
documentation for inspiration.
* Fewer words is better than more. Many Zulip users have English as a second
- Fewer words is better than more. Many Zulip users have English as a second
language.
* Try to put yourself in the shoes of a new Zulip user. What would you want
- Try to put yourself in the shoes of a new Zulip user. What would you want
to know?
* The goal of user-facing documentation is not to be comprehensive. The goal
- The goal of user-facing documentation is not to be comprehensive. The goal
is to give the right bits of information for the intended audience.
* Real estate in the left sidebar is somewhat precious. Minor features
- Real estate in the left sidebar is somewhat precious. Minor features
should rarely get their own article.
An anti-pattern is trying to make up for bad UX by adding user
@@ -98,17 +98,17 @@ allows .." rather than "we also allow ..". `You` is ok and used liberally.
Zulip's Markdown processor allows you to include several special features in
your documentation to help improve its readability:
* Since raw HTML is supported in Markdown, you can include arbitrary
- Since raw HTML is supported in Markdown, you can include arbitrary
HTML/CSS in your documentation as needed.
* Code blocks allow you to highlight syntax, similar to Zulip's own Markdown.
* Anchor tags can be used to link to headers in other documents.
* [Images](#images) of Zulip UI can be added to documentation.
* Inline [icons](#icons) used to refer to features in the Zulip UI.
* You can utilize [macros](#macros) to limit repeated content in the
- Code blocks allow you to highlight syntax, similar to Zulip's own Markdown.
- Anchor tags can be used to link to headers in other documents.
- [Images](#images) of Zulip UI can be added to documentation.
- Inline [icons](#icons) used to refer to features in the Zulip UI.
- You can utilize [macros](#macros) to limit repeated content in the
documentation.
* You can create special highlight warning blocks using
- You can create special highlight warning blocks using
[tips and warnings](#tips-and-warnings).
* You can create tabs using [Markdown tab switcher](#tab-switcher).
- You can create tabs using [Markdown tab switcher](#tab-switcher).
### Images
@@ -141,39 +141,39 @@ base class `icon-vector` and have dropped support for it. We now only support
icons from [FontAwesome](https://fontawesome.com/v4.7.0/) (version 4.7.0) which
make use of `fa` as a base class.
* cog (<i class="fa fa-cog"></i>) icon —
- cog (<i class="fa fa-cog"></i>) icon —
`cog (<i class="fa fa-cog"></i>) icon`
* down chevron (<i class="fa fa-chevron-down"></i>) icon —
- down chevron (<i class="fa fa-chevron-down"></i>) icon —
`down chevron (<i class="fa fa-chevron-down"></i>) icon`
* eye (<i class="fa fa-eye"></i>) icon —
- eye (<i class="fa fa-eye"></i>) icon —
`eye (<i class="fa fa-eye"></i>) icon`
* file (<i class="fa fa-file-code-o"></i>) icon —
- file (<i class="fa fa-file-code-o"></i>) icon —
`file (<i class="fa fa-file-code-o"></i>) icon`
* filled star (<i class="fa fa-star"></i>) icon —
- filled star (<i class="fa fa-star"></i>) icon —
`filled star (<i class="fa fa-star"></i>) icon`
* formatting (<i class="fa fa-font"></i>) icon —
- formatting (<i class="fa fa-font"></i>) icon —
`formatting (<i class="fa fa-font"></i>) icon`
* menu (<i class="fa fa-bars"></i>) icon —
- menu (<i class="fa fa-bars"></i>) icon —
`menu (<i class="fa fa-bars"></i>) icon`
* overflow ( <i class="fa fa-ellipsis-v"></i> ) icon —
- overflow ( <i class="fa fa-ellipsis-v"></i> ) icon —
`overflow ( <i class="fa fa-ellipsis-v"></i> ) icon`
* paperclip (<i class="fa fa-paperclip"></i>) icon —
- paperclip (<i class="fa fa-paperclip"></i>) icon —
`paperclip (<i class="fa fa-paperclip"></i>) icon`
* pencil (<i class="fa fa-pencil"></i>) icon —
- pencil (<i class="fa fa-pencil"></i>) icon —
`pencil (<i class="fa fa-pencil"></i>) icon`
* pencil and paper (<i class="fa fa-pencil-square-o"></i>) icon —
- pencil and paper (<i class="fa fa-pencil-square-o"></i>) icon —
`pencil and paper (<i class="fa fa-pencil-square-o"></i>) icon`
* plus (<i class="fa fa-plus"></i>) icon —
- plus (<i class="fa fa-plus"></i>) icon —
`plus (<i class="fa fa-plus"></i>) icon`
* smiley face (<i class="fa fa-smile-o"></i>) icon —
- smiley face (<i class="fa fa-smile-o"></i>) icon —
`smiley face (<i class="fa fa-smile-o"></i>) icon`
* star (<i class="fa fa-star-o"></i>) icon —
- star (<i class="fa fa-star-o"></i>) icon —
`star (<i class="fa fa-star-o"></i>) icon`
* trash (<i class="fa fa-trash-o"></i>) icon —
- trash (<i class="fa fa-trash-o"></i>) icon —
`trash (<i class="fa fa-trash-o"></i>) icon`
* video-camera (<i class="fa fa-video-camera"></i>) icon —
- video-camera (<i class="fa fa-video-camera"></i>) icon —
`video-camera (<i class="fa fa-video-camera"></i>) icon`
* x (<i class="fa fa-times"></i>) icon —
- x (<i class="fa fa-times"></i>) icon —
`x (<i class="fa fa-times"></i>) icon`
### Macros
@@ -186,22 +186,22 @@ The source for macros is the Markdown files under
`templates/zerver/help/include` in the
[main Zulip server repository](https://github.com/zulip/zulip).
* **Administrator only feature** `{!admin-only.md!}`: Notes that the feature
- **Administrator only feature** `{!admin-only.md!}`: Notes that the feature
is only available to organization administrators.
* **Message actions** `{!message-actions.md!}`: First step to navigating to
- **Message actions** `{!message-actions.md!}`: First step to navigating to
the on-hover message actions.
* **Message actions menu** `{!message-actions-menu.md!}`: Navigate to the
- **Message actions menu** `{!message-actions-menu.md!}`: Navigate to the
message actions menu.
* **Save changes** `{!save-changes.md!}`: Save changes after modifying
- **Save changes** `{!save-changes.md!}`: Save changes after modifying
organization settings.
* **Stream actions** `{!stream-actions.md!}`: Navigate to the stream actions
- **Stream actions** `{!stream-actions.md!}`: Navigate to the stream actions
menu from the left sidebar.
* **Start composing** `{!start-composing.md!}`: Open the compose box.
- **Start composing** `{!start-composing.md!}`: Open the compose box.
### Tips and warnings