MINOR: fix code listings security.html by jlprat · Pull Request #10770 · apache/kafka

jlprat · 2021-05-26T13:16:06Z

Fix examples under security.html so they use the right bash icon (>
instead of $) and also uses the right tool for showing code listings

Some of the diffs are caused also by the IDE aligning html code properly.

Committer Checklist (excluded from commit message)

Verify design and implementation
Verify test coverage and CI build status
Verify documentation (including upgrade notes)

Fix examples under security.html so they use the right bash icon (`>` instead of `$`) and also uses the right tool for showing code listings

jlprat · 2021-05-26T13:18:07Z

CC. @cadonna as you reviewed the last doc changes on formatting and styling, you might want to review these as well. I split the changes in several PRs so it's more bearable to review.

showuon

@jlprat , thanks for the PR. I had a quick look, and left some comments.

showuon · 2021-05-27T06:57:43Z

-            login module may be specified in the config value. If multiple mechanisms are configured on a
-            listener, configs must be provided for each mechanism using the listener and mechanism prefix.
-            For example,
+                    <p>Brokers may also configure JAAS using the broker configuration property <code>sasl.jaas.config</code>.


Line 402-408 has ol and li tag not get handled. Please help. Thanks.
https://github.com/apache/kafka/pull/10770/files#diff-3485b37e32662f4925ee0374c4f6eb1d4dfa589bbb1c148b2a70e92b4acbe8bdR402-R408

That li tag is currently closed at line 508. It's a 3 level nested ordered lists. Between line 402 and 508 we have the whole sublists as part of that li element. That's the reason the closing li element seems to be missing, it's just really down the page.

showuon · 2021-05-27T06:59:07Z

@@ -1835,28 +1834,28 @@ <h5 class="anchor-heading"><a id="operations_resources_and_protocols" class="anc
            <td></td>
            <td></td>
            <td>Creating delegation tokens has special rules, for this please see the
-                <a id="security_delegation_token" href="#security_delegation_token">Authentication using Delegation Tokens</a> section.</td>
+                <a id="security_delegation_token_1" href="#security_delegation_token">Authentication using Delegation Tokens</a> section.</td>


cadonna

@jlprat Thank you!

Here my feedback!

The added indentations sometimes do not match the previous section at the same level.

cadonna · 2021-05-27T10:14:24Z

+                    <p>Brokers may also configure JAAS using the broker configuration property <code>sasl.jaas.config</code>.
+                        The property name must be prefixed with the listener prefix including the SASL mechanism,
+                        i.e. <code>listener.name.{listenerName}.{saslMechanism}.sasl.jaas.config</code>. Only one
+                        login module may be specified in the config value. If multiple mechanisms are configured on a
+                        listener, configs must be provided for each mechanism using the listener and mechanism prefix.
+                        For example,


Why the indentation here? It should be on the same level as the previous paragraph, right?

Actually, it seems the above paragraphs should be indented to the right, there are several nested <ol> and <li> and <p> that didn't follow indentation.
I'm fixing these now.

I think we misunderstood each other. The line that starts with The property name ... should be aligned with <p>Brokers may also .... I am also fine, if you do not fix that. I think it is understandable and I see that the indentation is not really consistent in this file.

cadonna · 2021-05-27T10:21:56Z

-                    For example, <a href="#security_sasl_gssapi_clientconfig">GSSAPI</a>
-                    credentials may be configured as:
-                    <pre class="line-numbers"><code class="language-text">KafkaClient {
+                    If JAAS configuration is defined at different levels, the order of precedence used is:


Also this indentation do not seem to align to the previous section header JAAS configuration for Kafka brokers.

Same as previous, you are right, it needs to be aligned with the contents of the header JAAS configuration for Kafka brokers. However, the problem here was that the previous content was misaligned.

jlprat · 2021-05-27T11:00:41Z

Hi @cadonna thanks a lot for the feedback. I fixed the missing > characters. About the misalignment, you were right, however it was not from the lines you mention, but the previous ones.

cadonna

@jlprat Thank you for the update!

Here my feedback!

Once you answered to that, we can merge this PR and live with some indentation inconsistencies.

cadonna · 2021-06-01T08:47:27Z

+                    <p>Brokers may also configure JAAS using the broker configuration property <code>sasl.jaas.config</code>.
+                        The property name must be prefixed with the listener prefix including the SASL mechanism,
+                        i.e. <code>listener.name.{listenerName}.{saslMechanism}.sasl.jaas.config</code>. Only one
+                        login module may be specified in the config value. If multiple mechanisms are configured on a
+                        listener, configs must be provided for each mechanism using the listener and mechanism prefix.
+                        For example,


I think we misunderstood each other. The line that starts with The property name ... should be aligned with <p>Brokers may also .... I am also fine, if you do not fix that. I think it is understandable and I see that the indentation is not really consistent in this file.

jlprat · 2021-06-01T09:08:04Z

Thanks @cadonna All comments addressed!

cadonna · 2021-06-01T11:19:08Z

The test failures are unrelated since this is a pure doc change.

jlprat · 2021-06-01T12:00:14Z

Thanks @cadonna !

MINOR: fix code listings security.html

a5a6a61

Fix examples under security.html so they use the right bash icon (`>` instead of `$`) and also uses the right tool for showing code listings

showuon reviewed May 27, 2021

View reviewed changes

cadonna reviewed May 27, 2021

View reviewed changes

Add missing symbols and fix indentation of text block

bd77198

cadonna reviewed Jun 1, 2021

View reviewed changes

Adress comments

141fcbe

cadonna merged commit 054d5f9 into apache:trunk Jun 1, 2021

jlprat deleted the MINOR-fix-code-listings-security branch June 1, 2021 12:00

Conversation

jlprat commented May 26, 2021

Committer Checklist (excluded from commit message)

Uh oh!

jlprat commented May 26, 2021

Uh oh!

showuon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cadonna left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jlprat commented May 27, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cadonna left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jlprat commented Jun 1, 2021

Uh oh!

cadonna commented Jun 1, 2021

Uh oh!

jlprat commented Jun 1, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jlprat commented May 27, 2021 •

edited

Loading