Improve the Basic Authentication section

[MichalMaler]

Improve the Basic Authentication section

Adding intro for the BA section and also the information about how to configure it.

Close:
https://issues.redhat.com/browse/QDOCS-27
https://issues.redhat.com/browse/QDOCS-28

[quarkus-bot]

Thanks for your pull request!

The title of your pull request does not follow our editorial rules. Could you have a look?

• title should count at least 2 words to describe the change properly

This message is automatically generated by a bot.

[gsmet]

Hi @MichalMaler ,

A few comments on the form of the pull request:

• Please make the title of the PR a sentence similar to Improve the Basic Authentication section - it's important as they are included in our community release notes
• And then include the issue numbers in the description as you did
• And same for the commit comment

If you form your commit comment like:

Improve the Basic Authentication section

Close:
https://issues.redhat.com/browse/QDOCS-27
https://issues.redhat.com/browse/QDOCS-28

(note the blank line, it's important)

Then GitHub will automatically fill the fields appropriately when creating the pull request if you have only one commit and your work will be easier.

/cc @ebullient @quarkusio/documentation for general awareness.

[gsmet]

We never used this construct without an admonition type (e.g. [NOTE]) so we need to check how it renders on the website.

/cc @ebullient

[sberyozkin]

@gsmet Do you mean this one, _Authorization: Basic_ _<credentials>_ ?
I'd just go for a simple highlighting like Authorization: Basic <credentials>

[MichalMaler]

@sberyozkin I think he was talking about the ==== box I used to highlight the example.
The underscores mean a plain italic.

[gsmet]

Yes, what @MichalMaler said.

[ebullient]

Authorization: Basic <credentials> should be inline code, rather than italics, I believe.

Without the type (e.g. NOTE), it is a simple admonition that should render as a plain callout box, but we will have to see what the web CSS does with it.

[MichalMaler]

@gsmet Hello there. Thank you for the feedback. I applied what I could. Let see how it looks on the portal and if Erin will like it.
BTW, I tried to used the ./mvnw -f docs clean install command to build it locally, but I run into some 999-SNAPSHOT error.
Any idea how to make it work, please?

Cheers!

[gsmet]

@MichalMaler yeah, you need to do a full build first. Do a ./mvnw -DquicklyDocs then wait for a long time and you'll be all set.

Then you can iterate on the docs module as you wanted to do it without doing a full build every time. You might have to do it from time to time when we add a new module but it doesn't happen that often these days so you should be pretty much OK.

[hmanwani-rh]

@MichalMaler Thank you for creating this PR. The changes look great.
I'm adding a few suggestions to the changes to align with the style guide, please take a look and let me know if you've any questions.

[sberyozkin]

@MichalMaler @hmanwani-rh Thanks very much for this effort, LGTM, sorry if some of my suggestions look a bit pedantic. Your PR improves Basic Authentication related documentation a lot. I guess it is only the first step, eventually it will be moved into the dedicated doc(s)

[ebullient]

Just to confirm, this is a first pass at revising an existing doc, right? (I think I remember this).. we're kind of in the fuzzy middle to me on this one (a cross between a how-to and an explanation... )

[sberyozkin]

LGTM, I can merge shortly, my understanding is that right now the task is about getting the content right, the actual restructuring to align with new templates will follow up

[sberyozkin]

@ebullient right, just saw your comment, yes, that is my understanding too. The fist pass is about revising the current content for different security documents, preparing them really for the next phase and then in the next phase it will be a matter of moving the chunks of content around to align with the new model