This PR adds a basic .md template that is followed by lot of /api
pages. Since we have recently done the migration work to ensure that
our REST API documentation pages for individual endpoints are almost
all identical files following a common pattern, we can now get the
payoff of deleting them all in favor of a shared template.
This removes 2000 lines of somewhat finicky configuration from the
codebase, and thus should save significant effort when documenting new
API endpoints in the future.
The markdown files for endpoints or other pages which deviate from the
standard template remain, and the docs are instead generated from
those files using the existing system.
As a part of goal of moving towards a common template,
the hardcoded python tabs need to be removed to ensure
that endpoints which don't have python examples can be
covered by the common template as well.
This commit also modifies the markdown extension for python
examples to render empty string in case the examples don't
exist, which would allow it to be called whether the endpoint
has python examples or not.
We use the "does not accept any parameters" language in the common
template that we'll be migrating to shortly, so we remove this
variance (And adjust its test).
This commit modifies the templates to
auto-generate general descriptions of
responses directly from the newly
added field of x-response-description
as a part of the goal of a common template.
This commit modifies the templates to
auto-generate general descriptions of
parameters directly from the newly
added field of x-parameter-description
as a part of the goal of a common template.
Now, all possible configurations for curl examples
are rendered directly from openapi data, and
the templates should just call the markdown
function once.
This commit adjusts all the templates by removing
hardcoded configurations and descriptions for
individual curl examples.
We previously had a mix of "Filter users" and "Search people" for this
widget. "Search" is more correct because the right sidebar can only
show a subset of the organization in some settings.
This isn't the best writing, but it'll help us remember to cover these
details when we do a major pass on this article after adding upcoming
status changes.
This commit replaces the allow_community_topic_editing boolean with
integer field edit_topic_policy and includes both frontend and
backend changes.
We also update settings_ui.disable_sub_settings_onchange to not
change the color of label as we did previously when the setting
was a checkbox. But now as the setting is dropdown we keep the
label as it is and we don't do anything with label when disabling
dropdowns. Also, this function was used only here so we can safely
change this.
Currently, the `admin_config` configuration was
hardcoded in the templates, but as a goal of creating
a common template, we need to move all configurations
outside.
Moved the checking for function and language which need
admin_config out of templates into the code and added a
boolean `x-admin-config` to store whehter the operation
requires admin config.
Also, added the banner for admin access to auto-generate
if admin_config is present, and fixed the admin_config
for endpoints that were earlier missing it in the templates.
For this extraction, we need to move some context
parameter (from home_real in `views/home.py`) to extra
page_params parameter (of
build_page_params_for_home_page_load in
`lib/home.py`) so handlebars template can access them.
While moving I confirmed that these parameters are not
used elsewhere if some parameter is used elsewhere
(like `apps_page_url`) then I didn't remove it from the
context list, I just added it to the page_params list.
Fixes: #18795.
This results in moving the `zulip_merge_base` parameter to
page_params, so that it's available to JavaScript.
Since this is technically a tiny overlay, it needs to be initialized
before hashchange.js.
The javascript tab in .md templates can be
generated along with the line that adds js
example.
Further, as a part of the effort of moving
towards a single template, the markdown extension
for javascrit examples is modified to return empty
string if javascript example doesn't exist for that
endpoint. This would make it possible to cover more
endpoints with a single template.
The js example tabs are now automatically generated
during generation of javascript code, and so need to
be removed. Also, the markdown function to render js
examples can be added in all templates, since it is
parses and returns an empty string if the examples
don't exist, and allows us to move towards a common
template.
The pages have been verified to be correct
by using diff between old and new pages' raw HTML.
It's sufficiently tiny that the shared code benefits don't justify the
cost, given that we plan to move index.html to a different templating
system soon.
The headings for return values were currently hardcoded
in cases where they occur, but they can be rendered directly
in the markdown extension if the return values exist.
This should make it more intuitive to add
new elements to the compose box (such as
banners), and it also makes it a bit more
clear for styling purposes that the same
geometry happens whether the compose box
is open or the buttons are visible.
I lifted the #compose_container div into
the server template. It's not totally
clear to me why we need both #compose
and #compose_container, but there are
some scary comments about 1400px that
made me too timid to address that quirk.
In passing I removed a clearly redundant
click handler.
Tim Abbott
Suyash Vardhan Mathur
sahil839
Aman Agrawal
Vishnu KS
Riken Shah
Ganesh Pawar
Steve Howell