docs: admin api headers #5662
Merged
docs: admin api headers #5662
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This change modifies the admin api generation in two ways: * Adds a new "indent" css class to certain elements. This should increase those element's left margin. * Replaces some "bold text sections" (markdown sections whose title was bold text instead of a header) by "real sections" (markdown sections with headers). The reason we used bold text was to prevent it from appearing on the automated nav tables, but that is not a problem any more (nav tables only look at levels >= 3).
This introduces a max_level (value = 3) beyond which links will not be generated. In other words all h4 and h5s will be skipped when generating the Admin API navigation.
kikito
added a commit
to Kong/docs.konghq.com
that referenced
this pull request
Mar 11, 2020
This regenerates the Admin API docs using the changes included in Kong/kong#5662, which involve: * Replacing some "fake bold letters headers" with real headers * Adding the `indent` class to some of the generated headers and tables
hutchic
approved these changes
Mar 11, 2020
hishamhm
reviewed
Mar 11, 2020
| @@ -1104,8 +1104,9 @@ return { | |||
| to the field [health checker's threshold][healthchecks.threshold]. | |||
| ]], | |||
| endpoint = [[ | |||
| <div class="endpoint get">/upstreams/{name or id}/health/</div> | |||
| <div class="endpoint get indent">/upstreams/{name or id}/health/</div> | |||
There was a problem hiding this comment.
oh boy, I wish I had abstracted this div tag away back in the day
hishamhm
approved these changes
Mar 12, 2020
This table was a little too wide for our docs website. I have slightly reworded things so that it properly fits.
The current version of the PR generates some very long field names, like `healthchecks.active.unhealthy.tcp_failures`, as well as some very long default values, like `[200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]`. These very wide values are problematic when included inside tables, as code blocks (html does not know how to split them up, so they end up maximizing the tables, breaking layout and style). This change adds some "word breaks" (`<wbr>`) inside some of those long code blocks when they are inside tables, so that the browser knows it can break them at those points, fixing the table formatting issues.
kikito
added a commit
to Kong/docs.konghq.com
that referenced
this pull request
Mar 13, 2020
This regenerates the Admin API docs using the changes included in Kong/kong#5662, which involve: * Replacing some "fake bold letters headers" with real headers * Adding the `indent` class to some of the generated headers and tables * Splitting long field names and default values with word breaks so that they don't break table layouts
|
Thanks for the approvals! I added a couple new changes in order to deal with wrongly formatted tables (unrelated with the other issues fixed on this PR), hopefully the docs people will be satisfied with those. |
GayleNeumann
added a commit
to Kong/docs.konghq.com
that referenced
this pull request
Mar 20, 2020
* style(base/docs) tweak the heading sizes in docs This change increases the size difference of some of our docs headers. h1 gets slightly bigger, h6 gets significantly smaller. The rest of the headings are evenly distributed on the now wider gap. * style(docs) add a new .indent style for increasing indentation in docs * docs(2.0.0) regenerate admin API docs This regenerates the Admin API docs using the changes included in Kong/kong#5662, which involve: * Replacing some "fake bold letters headers" with real headers * Adding the `indent` class to some of the generated headers and tables * Splitting long field names and default values with word breaks so that they don't break table layouts * Update app/2.0.x/admin-api.md Co-Authored-By: lena-larionova <54370747+lena-larionova@users.noreply.github.com> Co-authored-by: Gayle Neumann <55467607+GayleNeumann@users.noreply.github.com> Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This change on the autodoc for the Admin API improves legibility on the Admin API headers and tables.
This has a sister PR in Kong/docs.konghq.com#1851