Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documenting ways for in-file and cross-file navigation #32154

Merged
merged 1 commit into from
May 16, 2023
Merged

Documenting ways for in-file and cross-file navigation #32154

merged 1 commit into from
May 16, 2023

Conversation

MichalMaler
Copy link
Contributor

After the xref and anchors clean-up and unification, I follow-up on @gsmet work and adding the steps for proper ID creations ant their calls.

Adding full specification to our contributors doc and light-weigh version for our templates.

Closing: https://issues.redhat.com/browse/QDOCS-267
Reference: #31981

Will squash n rebase after a review.

@MichalMaler MichalMaler requested a review from gsmet March 27, 2023 11:16
@michelle-purcell
Copy link
Contributor

@MichalMaler - reviewing now. Thanks

gsmet
gsmet previously requested changes Mar 27, 2023
View reviewed changes
Copy link
Member

@gsmet gsmet left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I suggested a few changes (once).

I don't understand why we duplicate this content so many times? It will be a nightmare to maintain.

docs/src/main/asciidoc/_templates/template-concept.adoc Outdated Show resolved Hide resolved
docs/src/main/asciidoc/_templates/template-concept.adoc Outdated Show resolved Hide resolved
@MichalMaler
Copy link
Contributor Author

MichalMaler commented Mar 27, 2023 •
edited
Loading

Thanks. I suggested a few changes (once).

I don't understand why we duplicate this content so many times? It will be a nightmare to maintain.

The task was to add this to contributor and other related docs, and since many dont read the contributor docs while at least using templates to create a new file, I add this info to our templates too (so there is a chance that before removing of the content from the template they will read it).
Ofc, this is just a proposal. If we agree to keep it only in the contrib doc or just on one places, I will do the changes.
I think its good to have this info in templates, since we got many questions about creating cross-file xrefs and so on. Also, the content of templates is just to provide info before its deletion, so why not add something useful there.

@gsmet Thank you for the review

@MichalMaler MichalMaler force-pushed the QUARKUS-0dc30d1-Docummenting-xref_anchros-use branch from 77dacd4 to 2bb430f Compare March 27, 2023 18:26
michelle-purcell
michelle-purcell approved these changes Mar 28, 2023
View reviewed changes
Copy link
Contributor

@michelle-purcell michelle-purcell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MichalMaler - Nice job 👍
Please see my suggestion for how you could avoid duplicating the same content in several places. Thanks.

@MichalMaler
Copy link
Contributor Author

@MichalMaler - Nice job +1 Please see my suggestion for how you could avoid duplicating the same content in several places. Thanks.

@michelle-purcell Thank you for the review and suggestions, Michelle. Lets make it work!

@MichalMaler MichalMaler force-pushed the QUARKUS-0dc30d1-Docummenting-xref_anchros-use branch 2 times, most recently from 2c3fa26 to a3bc5ff Compare March 28, 2023 11:52
@MichalMaler
Copy link
Contributor Author

@michelle-purcell @gsmet Applied all your suggestions in my own way :)

Content is now added to Upstream docs in these two places and forms:

  1. doc-contribute-docs-howto.adoc#anchors-howto
  • Headings respecting HowTo style
  • Content pointing towards -> doc-reference.adoc#cross-references
  • Content written in a way that it provides steps with some background information

2)doc-reference.adoc#cross-references

  • Provides minimalistic and light-weight version of the previously mentioned HowTo content (just instructions in bullet items to better match the reference template style)
  • Pointing towards the first doc.

Templates now only contain xrefs where a contributor can get the information if needed thus nut duplicating the content.

@MichalMaler MichalMaler force-pushed the QUARKUS-0dc30d1-Docummenting-xref_anchros-use branch 2 times, most recently from a47f2bf to ee473be Compare March 28, 2023 12:23
michelle-purcell
michelle-purcell approved these changes Mar 28, 2023
View reviewed changes
Copy link
Contributor

@michelle-purcell michelle-purcell left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MichalMaler - Super job! Looks great. Thank you 💚

@github-actions
Copy link

github-actions bot commented Mar 28, 2023 •
edited
Loading

🙈 The PR is closed and the preview is expired.

@MichalMaler MichalMaler force-pushed the QUARKUS-0dc30d1-Docummenting-xref_anchros-use branch from ee473be to 118263a Compare March 28, 2023 13:30
@quarkus-bot
Copy link

quarkus-bot bot commented Mar 28, 2023

✔️ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

ebullient
ebullient reviewed Mar 29, 2023
View reviewed changes
docs/src/main/asciidoc/doc-contribute-docs-howto.adoc Outdated Show resolved Hide resolved
docs/src/main/asciidoc/doc-contribute-docs-howto.adoc Outdated Show resolved Hide resolved
docs/src/main/asciidoc/doc-reference.adoc Outdated Show resolved Hide resolved
docs/src/main/asciidoc/doc-reference.adoc Outdated Show resolved Hide resolved
@MichalMaler MichalMaler force-pushed the QUARKUS-0dc30d1-Docummenting-xref_anchros-use branch from 87a0245 to 236bc41 Compare March 29, 2023 17:38
@MichalMaler
Copy link
Contributor Author

@ebullient Thank you Erin. Added your suggestions. This can be merged at will now.

@MichalMaler
Copy link
Contributor Author

Thanks. I suggested a few changes (once).

I don't understand why we duplicate this content so many times? It will be a nightmare to maintain.

@gsmet Can we merge this if you agree?

@MichalMaler MichalMaler force-pushed the QUARKUS-0dc30d1-Docummenting-xref_anchros-use branch 2 times, most recently from 32870dd to 4f7c5fa Compare April 3, 2023 11:28
@ebullient
Copy link
Member

crap. I messed that up. will try to fix

@ebullient ebullient force-pushed the QUARKUS-0dc30d1-Docummenting-xref_anchros-use branch from 33139ed to c400e43 Compare April 11, 2023 17:33
@MichalMaler
Copy link
Contributor Author

@ebullient Did not spot anything broken.

@ebullient ebullient force-pushed the QUARKUS-0dc30d1-Docummenting-xref_anchros-use branch from c400e43 to 36605f3 Compare April 14, 2023 17:22
@MichalMaler @ebullient
Doc reference edits
0a428ea 
Signed-off-by: Michal Maléř <[email protected]>

Docummenting ways for in-file and cross-file navigation

Signed-off-by: Michal Maléř <[email protected]>

Review

Signed-off-by: Michal Maléř <[email protected]>

Review and fixes

Signed-off-by: Michal Maléř <[email protected]>

Review and fixes

Signed-off-by: Michal Maléř <[email protected]>

Review and fixes

Signed-off-by: Michal Maléř <[email protected]>

Review and fixes

Signed-off-by: Michal Maléř <[email protected]>

Review and fixes

Signed-off-by: Michal Maléř <[email protected]>

Apply suggestions from code review

Co-authored-by: Erin Schnabel <[email protected]>

Apply suggestions from code review

Co-authored-by: Erin Schnabel <[email protected]>
@MichalMaler MichalMaler force-pushed the QUARKUS-0dc30d1-Docummenting-xref_anchros-use branch from e7b601d to 0a428ea Compare May 16, 2023 10:33
@MichalMaler
Copy link
Contributor Author

@maxandersen Hello Max. This PR was approved by other writers and Erin. Please, what needs to be done so that we can merge this?
Thank you

@MichalMaler
Copy link
Contributor Author

Thank you for the approval @jmartisk

@gsmet gsmet dismissed their stale review May 16, 2023 11:37

Dismissed.

@ebullient ebullient merged commit e2c3b4e into quarkusio:main May 16, 2023
@quarkus-bot quarkus-bot bot added this to the 3.1 - main milestone May 16, 2023
@MichalMaler MichalMaler deleted the QUARKUS-0dc30d1-Docummenting-xref_anchros-use branch May 16, 2023 11:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@michelle-purcell michelle-purcell michelle-purcell approved these changes

@jmartisk jmartisk jmartisk approved these changes

@ebullient ebullient ebullient approved these changes

@gsmet gsmet Awaiting requested review from gsmet

Assignees
No one assigned
Labels
area/documentation
Projects
None yet
Milestone
3.1.0.CR1
Development

Successfully merging this pull request may close these issues.
5 participants
@MichalMaler @michelle-purcell @ebullient @jmartisk @gsmet