Updates the tutorial in "Writing help center articles: Writing
style" for using `<kbd>` HTML elements when documenting keyboard
shortcuts in help center articles.
Also, adds section about the keyboard tip macro/syntax.
We create "event-filter-instruction.md" and add it to
"create-bot-construct-url.md". This allows the user to keep track of the
supported event types for most of the integrations that implement this
feature. Note that not all integrations use "create-bot-construct-url.md".
We also need to rename "function" to "view_function" to make this change
type-check.
This is relevant to #18392.
Signed-off-by: Zixuan James Li <p359101898@gmail.com>
Creates `zerver.lib.url_redirects.py` to record old and new URLs
for documentation pages that have been renamed/moved and need URL
redirects.
This file is then used by `zproject.urls.py` to redirect links and
by `zerver.test.test_urls.py` to test that all of the old URLs
return a success response with a common page header/text depending
on the type of redirect (help center, policy, or API).
Adds a section to contributor docs on writing documentation for
how to use this redirect system when renaming a help center or api
documentation page.
Fixes#21946. Fixes#17897.
Adds a section for writing and style guidlines to the tutorial
for writing help center articles. Moves the sections on 'Voice'
and 'User interface' to be in the new section, and adds a section
on 'Keyboard shortcuts'.
The content in `zulip-config.md` was moved (in #22315) to
`change-zulip-config.file.md`. This removes the now out-of-date
reference to this macro in the documentation for writing
integrations and removes the file as it is no longer in use.
markdown-include is GPL licensed.
Also, rewrite it as a block processor, so that it works correctly
inside indented blocks.
Signed-off-by: Anders Kaseorg <anders@zulip.com>
This uses the myst_heading_anchors option to automatically generate
header anchors and make Sphinx aware of them. See
https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors.
Note: to be compatible with GitHub, MyST-Parser uses a slightly
different convention for .md fragment links than .html fragment links
when punctuation is involved. This does not affect the generated
fragment links in the HTML output.
Fixes#13264.
Signed-off-by: Anders Kaseorg <anders@zulip.com>
We previously had a convention of redundantly including the directory
in relative links to reduce mistakes when moving content from one file
to another. However, these days we have a broken link checker in
test-documentation, and after #21237, MyST-Parser will check relative
links (including fragments) when you run build-docs.
Signed-off-by: Anders Kaseorg <anders@zulip.com>
Renames `/docs/documentation/user.md` to reflect the rebranding
from "user documentation" to "help center documentation".
Also, fixes any linking in the docs to that file.
Updates the tutorial for writing help center articles to encourage
contributors to add to or enhance the existing help center docs
before writing a new articles for new features.
Also, generally updates references to 'user documentation' to be
'help center documentation'.
Additionally, updates some headers within the tutorials for clarity
and consistency, and adds some linkifying throughout the section on
writing documentation.
Expands the developer tutorial 'Writing a new application feature' to
include more detail about the documentation aspects of adding a new
feature. Adds references to specific files that will be impacted and
highlights API changes as well as writing `/help` articles.
Recently, the need for individual Markdown templates for
every endpoint's OpenAPI page was removed, as they are now
auto-generated from OpenAPI data. Further, as a part of this
migration, several new fields and Markdown extensions were added.
This commit updates the documentation to reflect the changes that
have occured as a result of the migration.
With various edits by tabbott to clarify or simplify the documentation.
Previously, one needed to specifying all the HTTP status
codes that we want to render along with the operation,
but the primary use case just needs the responses of
all the status codes, and not just one.
This commit modifies the Markdown extension to render
all the responses of all status codes of a specified
operation in a loop.
Make it easier to locate docs for how to build an integration by adding
a link to the docs at the top of the docs on how to document an
integration.
Tweaked by tabbott to adjust the whole first paragraph and make the
link more contextual.
I have made `tools/setup/optimize-svg` do the SVG optimization
automatically rather than just telling you the command to run if they
need optimizing. This included adding a `--check` parameter to use in
CI to only check as we previously did rather than actually running the
optimization.
I have also made `tools/setup/optimize-svg` execute
`tools/setup/generate_integration_bots_avatars.py` once it has run the
optimization to ensure it is always ran.
This makes it one less command to run when creating an integration,
but also means that we catch instances where a PNG has just been
copied into the `static/images/integrations/bot_avatars` folder as the
only instance where this won't be run is if `optimize-svg` has not
been run which would be caught in CI.
Fixes#18183. Fixes#18184.
I have updated the path for the svgo module in the integrations
documentation as the other path would error out as `svgo` wasn't in
PATH, so have updated to use `yarn run svgo` instead.
I have updated the `Documenting an Integration` documentation to be more
accurate on the usage of `tools/generate-integration-docs-screenshot` as
well as the requirement to fill out the `DOC_SCREENSHOT_CONFIG` section
of `zerver/lib/integrations.py` and a few other minor changes.
c2f9227892 switched from a long hard-coded list in `TEST_FUNCTIONS` to
using a new `@openapi_test_function` decorator; update the
documentation about writing API docs accordingly.
This commit is first of few commita which aim to change all the
bugdown references to markdown. This commits rename the files,
file path mentions and change the imports.
Variables and other references to bugdown will be renamed in susequent
commits.
Lauryn Menard
David Rosa
Zixuan James Li
Anders Kaseorg
Lauryn Menard
Tim Abbott
Suyash Vardhan Mathur
Suyash Vardhan Mathur
Adam Birds
Janneke Morin
Sumanth V Rao
Vishnu KS
Alex Vandiver
Mohit Gupta