You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jira@kafka.apache.org by GitBox <gi...@apache.org> on 2020/11/27 12:28:36 UTC
[GitHub] [kafka] tombentley opened a new pull request #9658: Linking to config parameters
tombentley opened a new pull request #9658:
URL: https://github.com/apache/kafka/pull/9658
This demos an idea I had for improving the website docs.
The docs often mention config parameters. With recent changes it's now possible to deep link directly to the the doc for a given config parameter. It would be useful for readers if we made use of this in our own docs, so when talking about `listeners` in prose we link to the doc for it.
This PR achieves that in a relatively easy-to-author way using a CSS class on the `<code>` used to wrap some config parameters and some JS which takes the class and the included text and turns it into one or more links. For example `<code class="brokerconfig">listeners</code>` gets turned into a link to the doc for [`listeners`](https://kafka.apache.org/27/documentation.html#brokerconfigs_listeners), with similar classes for topic, producer consumer etc. configs.
Here a're some screenshots of what the markup changes in the patch result in, first from the upgrade section:
The script knows to ignore whatever is after the `=` sign. Here's another example from the security section (please excuse the magenta find-in-page highlighting):
Because the script checks for the existence of the link before generating the link it doesn't linkify the `username` or `password` (the regex isn't powerful enough to properly understand that lines ending with `\` are continuation lines). This is a bit of a hack, but it works well enough.
There's two potential issues I can see with this:
1. Lots of client configs are shared between both producer and consumer (and admin client...), so which should we link to? Probably a link is better than no link, but equally we could chose not to link such configs.
2. This is not really compatible with https://issues.apache.org/jira/browse/KAFKA-2967 though it might be possible to do something similar in ReStructuredText with custom roles.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [kafka] tombentley commented on pull request #9658: Linking to config parameters
Posted by GitBox <gi...@apache.org>.
tombentley commented on pull request #9658:
URL: https://github.com/apache/kafka/pull/9658#issuecomment-734812701
Thoughts?
@mimaison, @chia7712, @omkreddy
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org