Doc style and link enhancements

[michelle-purcell]

This PR fixes style issues (title capitalization, one sentence per line...), links, and some grammar as per the preferred Quarkus Contributor guidelines for writing tutorials.
This also harmonizes the content with product docs downstream for the 3.2 release.

[sberyozkin]

Looks like it was cancelled and I missed merging it.

[sberyozkin]

It is upstream only though so let me merge it now, though I'll rebase

[sberyozkin]

Hmm, exec-maven-plugin:3.0.0:exec (assemble-downstream-doc) @ quarkus-documentation is hanging, but I think it just finished on my laptop, I was checking Michelle's branch.

[sberyozkin]

@gsmet I'm not sure why this PR is hanging, I don't see anything in the updated doc that could've caused it. Please review and merge if it looks fine. on PTO tomorrow

[sberyozkin]

@sheilamjones, @inoxx03, Hi - what is assemble-downstream-doc ? The doc build is hanging and I don't know if I can merge this PR or not

[inoxx03]

@sberyozkin Thasnk for the head's up. TBH, I have not found the cause yet. trheI'm not sure but assemble-downstream-doc might be one of the post-processing jobs that we use to transform parts of thew upstream doc's AsciiDoc source to get around the downstream publishing system limitations.

I'll come back and investigate further today, just have to finish some release-related tasks.

[sheilamjones]

Apologies for slow reply @sberyozkin. Was tied up with 3.2 release tasks yesterday. Yes, as Stefan suggested, I think the assemble-downstream.doc topic relates to the downstreaming script with the post-processing fixes to enable us to bring the content downstream. Shall investigate further.

[sberyozkin]

@sheilamjones No problems at all Sheila, thanks for the update.

Unfortunately it is still failing, something in this PR or in some other PRs is causing this task to fail.

@rsvoboda Rostislav, can you spot it ? Your fix is in Michelle's branch: https://github.com/michelle-purcell/quarkus/commits/security-doc-fixes-3-2-bearer-concept

[rsvoboda]

This noise makes the build of downstream docs to be stuck

there should be no + and ==== on solo lines

CC @sberyozkin @michelle-purcell

[sberyozkin]

@rsvoboda @michelle-purcell It took me may be 5 rounds to get past the downstream task, I've ended up removing all of standalone + and ==== and it looked like it fixed the problem. Michelle, not sure if the end result would be what you expected it to be without these characters, so I guess you should have a look before me merging this PR

Thanks

[github-actions]

🙈 The PR is closed and the preview is expired.

[sberyozkin]

Michelle, I'm not sure the numbering scheme works, there are a few places with 1. where another .1 follows in the same section after one paragraph etc. Can we consider removing it ?

[michelle-purcell]

Thanks @sberyozkin. Apologies for not getting to this sooner. Between PTO and other priorities...
Some of the numbering markup edits were introduced to fix bad numbering/style on the downstream publishing output too and to follow the advice in the upstream tutorial/how-to templates.
I will test and investigate today and test the output of the markup on both publishing platforms. Thanks for flagging :-)

[sberyozkin]

Hi Michelle @michelle-purcell , missed your comment, sorry. Sure please check it

[michelle-purcell]

Closing this PR as it has languished and overlaps with other changes. @rolfedh is taking over the edits for this guide in a fresh PR. Thanks @rolfedh. Please see the comments above for your reference. Thanks.

[rolfedh]

@rolfedh is taking over the edits for this guide in a fresh PR. Thanks @rolfedh. Please see the comments above for your reference. Thanks.

@sheilamjones has taken up revising this guide. I've conveyed this information to her. Thanks.