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

Make asciidoc indexes and file names more consistent #1612

Closed
wants to merge 31 commits into from
Closed

Make asciidoc indexes and file names more consistent #1612

Show file tree
Hide file tree
Changes from 26 commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
40e9d71
Make filename and asciidoc identifers consistent
rhaetor Nov 23, 2024
d9fcea1
Make filename and asciidoc identifers consistent
rhaetor Nov 23, 2024
478a590
Cleanup
rhaetor Nov 23, 2024
e1ac54e
Nav and index changes
rhaetor Nov 23, 2024
72bcb7c
Minor fix
rhaetor Nov 23, 2024
6ec37ec
Nav fix
rhaetor Nov 23, 2024
dc9661c
https://
rhaetor Nov 23, 2024
0115360
https://
rhaetor Nov 23, 2024
54babec
{version}
rhaetor Nov 23, 2024
a607219
{version}
rhaetor Nov 23, 2024
55d905c
Another ID
rhaetor Nov 23, 2024
6ba3f87
Another ID
rhaetor Nov 23, 2024
5d42441
Implicit ID to explicit
rhaetor Nov 23, 2024
a3aea78
Implicit ID to explicit
rhaetor Nov 23, 2024
b71ecc0
Consistent crossreferences
rhaetor Nov 23, 2024
42fbb92
Typos
rhaetor Nov 23, 2024
491d5a5
NOTE and IMPORTANT admonitions
rhaetor Nov 23, 2024
6d90444
Xref fix
rhaetor Nov 23, 2024
1da092c
Error in tag replacement
rhaetor Nov 23, 2024
9d96f2a
images
rhaetor Nov 23, 2024
85dec0e
Duplicate examples.
rhaetor Nov 23, 2024
76f6bf3
Duplicate id:s, language.
rhaetor Nov 23, 2024
e76940b
Nav
rhaetor Nov 24, 2024
38903f7
Nav
rhaetor Nov 24, 2024
2953025
NOTE
rhaetor Nov 24, 2024
43aa428
capitalization
rhaetor Nov 24, 2024
80edd60
Extensions markers in nav
rhaetor Dec 3, 2024
7b84c30
Removed link #fragments
rhaetor Dec 3, 2024
d5304bc
IMPORTANT admonition
rhaetor Dec 3, 2024
53e3cb3
IMPORTANT admonition
rhaetor Dec 3, 2024
2b1f499
Documentation style guide rules:
rhaetor Dec 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
0 docs/modules/ROOT/images/code.quarkus.io.png → docs/modules/ROOT/images/code-quarkus-io.png
View file
Open in desktop
File renamed without changes
0 ...OOT/images/release-notes-2.10.0-since.png → ...OOT/images/release-notes-2-10-0-since.png
View file
Open in desktop
File renamed without changes
0 ...es/release-notes-2.7.0-devui-services.png → ...es/release-notes-2-7-0-devui-services.png
View file
Open in desktop
File renamed without changes
74 changes: 42 additions & 32 deletions docs/modules/ROOT/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
// user-guide
* xref:user-guide/index.adoc[User guide]
** xref:user-guide/create-project.adoc[Create a new project]
** xref:user-guide/first-soap-web-service.adoc[Your first SOAP Web service]
Expand Down Expand Up @@ -27,45 +28,55 @@
*** xref:user-guide/advanced-client-topics/prevent-resource-leaks.adoc[Prevent resource leaks]
** xref:user-guide/camel-integration.adoc[Camel Integration]
** xref:user-guide/examples.adoc[Examples]

// security-guide
* xref:security-guide/index.adoc[Security guide]
** xref:user-guide/ssl.adoc[SSL, TLS and HTTPS]
** xref:user-guide/auth.adoc[Authentication and authorization]
** xref:security-guide/ws-securitypolicy-auth.adoc[WS-SecurityPolicy Authentication]
** xref:user-guide/ssl-tls-https.adoc[SSL, TLS and HTTPS]
** xref:user-guide/authentication-authorization.adoc[Authentication and authorization]
** xref:security-guide/ws-securitypolicy-authentication-authorization.adoc[WS-SecurityPolicy Authentication]
Comment on lines +34 to +36
Copy link
Contributor

Choose a reason for hiding this comment

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

We would have to add page-aliases attribute set to the old name, so that Antora cares for redirects. (I need to test how well page-aliases work at all.) Otherwise we'd break external links, which I'd prefer to avoid.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think page-alias should work, but I can't swear to it.

Why I changed it is so we have consistent main headers, file names and links. Maybe I went overboard here.


// release-notes
* xref:release-notes/index.adoc[Release notes]

ifeval::[{doc-is-main} == true]
** xref:release-notes/3.15.0.adoc[3.15.0 LTS]
** xref:release-notes/3.14.0.adoc[3.14.0]
** xref:release-notes/3.13.1.adoc[3.13.1]
** xref:release-notes/3.13.0.adoc[3.13.0]
** xref:release-notes/3.12.0.adoc[3.12.0]
** xref:release-notes/3.11.1.adoc[3.11.1]
** xref:release-notes/3.11.0.adoc[3.11.0]
** xref:release-notes/3.10.0.adoc[3.10.0]
** xref:release-notes/3.9.0.adoc[3.9.0]
** xref:release-notes/3.8.6.adoc[3.8.6 LTS]
** xref:release-notes/3.8.5.adoc[3.8.5 LTS]
** xref:release-notes/3.8.4.adoc[3.8.4 LTS]
** xref:release-notes/3.8.3.adoc[3.8.3 LTS]
** xref:release-notes/3.8.2.adoc[3.8.2 LTS]
** xref:release-notes/3.8.1.adoc[3.8.1 LTS]
** xref:release-notes/3.8.0.adoc[3.8.0 LTS]
** xref:release-notes/2.7.1.adoc[2.7.1]
** xref:release-notes/2.7.0.adoc[2.7.0]
** xref:release-notes/2.6.1.adoc[2.6.1]
** xref:release-notes/2.6.0.adoc[2.6.0]
** xref:release-notes/2.5.0.adoc[2.5.0]
** xref:release-notes/2.4.0.adoc[2.4.0]
** xref:release-notes/2.3.1.adoc[2.3.1]
** xref:release-notes/2.3.0.adoc[2.3.0]
** xref:release-notes/2.2.2.adoc[2.2.2 LTS]
** xref:release-notes/2.2.1.adoc[2.2.1 LTS]
** xref:release-notes/2.2.0.adoc[2.2.0 LTS]
** xref:release-notes/rn-3-15-0.adoc[3.15.0 LTS]
** xref:release-notes/rn-3-14-0.adoc[3.14.0]
** xref:release-notes/rn-3-13-1.adoc[3.13.1]
** xref:release-notes/rn-3-13-0.adoc[3.13.0]
** xref:release-notes/rn-3-12-0.adoc[3.12.0]
** xref:release-notes/rn-3-11-1.adoc[3.11.1]
** xref:release-notes/rn-3-11-0.adoc[3.11.0]
** xref:release-notes/rn-3-10-0.adoc[3.10.0]
** xref:release-notes/rn-3-9-0.adoc[3.9.0]
** xref:release-notes/rn-3-8-6.adoc[3.8.6 LTS]
** xref:release-notes/rn-3-8-5.adoc[3.8.5 LTS]
** xref:release-notes/rn-3-8-4.adoc[3.8.4 LTS]
** xref:release-notes/rn-3-8-3.adoc[3.8.3 LTS]
** xref:release-notes/rn-3-8-2.adoc[3.8.2 LTS]
** xref:release-notes/rn-3-8-1.adoc[3.8.1 LTS]
** xref:release-notes/rn-3-8-0.adoc[3.8.0 LTS]
** xref:release-notes/rn-2-7-1.adoc[2.7.1]
** xref:release-notes/rn-2-7-0.adoc[2.7.0]
** xref:release-notes/rn-2-6-1.adoc[2.6.1]
** xref:release-notes/rn-2-6-0.adoc[2.6.0]
** xref:release-notes/rn-2-5-0.adoc[2.5.0]
** xref:release-notes/rn-2-4-0.adoc[2.4.0]
** xref:release-notes/rn-2-3-1.adoc[2.3.1]
** xref:release-notes/rn-2-3-0.adoc[2.3.0]
** xref:release-notes/rn-2-2-2.adoc[2.2.2 LTS]
** xref:release-notes/rn-2-2-1.adoc[2.2.1 LTS]
** xref:release-notes/rn-2-2-0.adoc[2.2.0 LTS]
Comment on lines +42 to +68
Copy link
Contributor

Choose a reason for hiding this comment

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

I would not mind the short prefix, but why not the verbatim version with dots in the name? It is much easier to copy/paste/search/replace when looking for/editing the stuff.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I had links break because of periods in the anchors, so wanted to avoid them completely. Not sure if this solution is all that brilliant.

endif::[]

// release-planning
* xref:release-planning.adoc[Release planning]
* xref:contributor-guide/index.adoc[Contributor guide]
** xref:contributor-guide/releasing.adoc[Releasing]

// reference
* xref:reference/index.adoc[Reference]
// extensions: START
Copy link
Contributor

Choose a reason for hiding this comment

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

This markers may not be removed bc. they are used by a maven plugin generating this part of the navigation.

Extension come and go and the plugin helps to keep the nav. up to date. It is not such a big problem with QCXF, because we do not have that many extensions. I just copyied the approach from Camel Quarkus, where they are so many that there is no other way than doing it with a tool.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Is the plugin using the marks, or generating them?


// extensions
** xref:reference/extensions/quarkus-cxf.adoc[Quarkus CXF]
** xref:reference/extensions/quarkus-cxf-rt-features-metrics.adoc[Metrics Feature]
** xref:reference/extensions/quarkus-cxf-integration-tracing-opentelemetry.adoc[OpenTelemetry]
Expand All @@ -74,4 +85,3 @@ endif::[]
** xref:reference/extensions/quarkus-cxf-services-sts.adoc[Security Token Service (STS)]
** xref:reference/extensions/quarkus-cxf-rt-transports-http-hc5.adoc[HTTP Async Transport]
** xref:reference/extensions/quarkus-cxf-xjc-plugins.adoc[XJC Plugins]
// extensions: END
Copy link
Contributor

Choose a reason for hiding this comment

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

Same as previous, the marker has to come back.

2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/contributor-guide/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[[contributor-guide]]
[[contributor-guide-index]]
= Contributor guide


Expand Down
16 changes: 9 additions & 7 deletions docs/modules/ROOT/pages/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,25 @@
[[cxf-extension-for-quarkus]]
[[quarkus-cxf-index]]
= {quarkus-cxf-project-name}

This project aims at porting http://cxf.apache.org/[Apache CXF] to https://quarkus.io/[Quarkus] runtime
including full support for producing https://quarkus.io/container-first/[GraalVM native images].

[IMPORTANT]
====
While http://cxf.apache.org/[Apache CXF] implements wide range of standards and specifications,
{quarkus-cxf-project-name} is currently focusing *only* on supporting the ones related to
*Simple Object Access Protocol* (https://en.wikipedia.org/wiki/SOAP[SOAP])
and *Java API for XML Web Services* (https://en.wikipedia.org/wiki/JAX-WS[JAX-WS]).
Refer to xref:reference/index.adoc[Reference] to learn which parts of CXF are supported.
Refer to xref:reference/index.adoc#reference-index[Reference] to learn which parts of CXF are supported.
====

The documentation is divided into the following main parts:

* xref:user-guide/index.adoc[User guide] - explains the typical usage of {quarkus-cxf-project-name}
* xref:security-guide/index.adoc[Security guide] - documents various security related aspects of {quarkus-cxf-project-name}, such as SSL/TLS, Authentication and Authorization
* xref:release-notes/index.adoc[Release notes] - Release notes documents for the past releases
* xref:release-planning.adoc[Release planning] - when new releases of {quarkus-cxf-project-name} are to be expected
* xref:reference/index.adoc[Reference] - the full list of supported specifications, use cases and configuration options
* xref:user-guide/index.adoc#user-guide-index[User guide] - explains the typical usage of {quarkus-cxf-project-name}
* xref:security-guide/index.adoc#security-guide-index[Security guide] - documents various security related aspects of {quarkus-cxf-project-name}, such as SSL/TLS, Authentication and Authorization
* xref:release-notes/index.adoc#release-notes-index[Release notes] - Release notes documents for the past releases
* xref:release-planning.adoc#release-planning[Release planning] - when new releases of {quarkus-cxf-project-name} are to be expected
* xref:reference/index.adoc#reference-index[Reference] - the full list of supported specifications, use cases and configuration options
Copy link
Contributor

Choose a reason for hiding this comment

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

I see why these *-index anchors are needed. We break the external links, but it is perhaps not that important in this specific case. Hence I am fine with the change.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I am open to suggestions on how to solve the problem another way. At the time I had no better idea.


[[issues-and-support]]
== Issues and Support
Expand Down
12 changes: 7 additions & 5 deletions ...T/pages/reference/extensions/quarkus-cxf-integration-tracing-opentelemetry.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,12 @@ endif::[]

Generate https://opentelemetry.io/[OpenTelemetry] https://opentelemetry.io/docs/concepts/signals/traces/[traces].

IMPORTANT: OpenTelemetry Metrics and Logging are not supported yet on neither Quarkus nor CXF side,
hence {quarkus-cxf-project-name} cannot support them either. Tracing is thus
the only OpenTelemetry feature supported by this extension.

[IMPORTANT]
====
OpenTelemetry Metrics and Logging are not supported yet on neither Quarkus nor CXF side,
hence {quarkus-cxf-project-name} cannot support them either. Tracing is thus
the only OpenTelemetry feature supported by this extension.
====
rhaetor marked this conversation as resolved.
Show resolved Hide resolved

[id="quarkus-cxf-integration-tracing-opentelemetry-maven-coordinates"]
== Maven coordinates
Expand All @@ -36,7 +38,7 @@ or add these coordinates to your existing project:
ifeval::[{doc-show-user-guide-link} == true]
[TIP]
====
Check the xref:user-guide/index.adoc[User guide] and especially its
Check the xref:user-guide/index.adoc#user-guide-index[User guide] and especially its
xref:user-guide/create-project.adoc#dependency-management[Dependency management] section
for more information about writing applications with {quarkus-cxf-project-name}.
====
Expand Down
12 changes: 7 additions & 5 deletions docs/modules/ROOT/pages/reference/extensions/quarkus-cxf-rt-features-metrics.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,12 @@ endif::[]

Collect metrics using https://micrometer.io/[Micrometer].

IMPORTANT: Unlike https://cxf.apache.org/docs/metrics.html[CXF Metrics feature],
this {quarkus-cxf-project-name} extension does not support https://cxf.apache.org/docs/dropwizard-metrics.html[Dropwizard Metrics].
Only Micrometer is supported.

[IMPORTANT]
====
Unlike https://cxf.apache.org/docs/metrics.html[CXF Metrics feature],
this {quarkus-cxf-project-name} extension does not support https://cxf.apache.org/docs/dropwizard-metrics.html[Dropwizard Metrics].
Only Micrometer is supported.
====

[id="quarkus-cxf-rt-features-metrics-maven-coordinates"]
== Maven coordinates
Expand All @@ -36,7 +38,7 @@ or add these coordinates to your existing project:
ifeval::[{doc-show-user-guide-link} == true]
[TIP]
====
Check the xref:user-guide/index.adoc[User guide] and especially its
Check the xref:user-guide/index.adoc#user-guide-index[User guide] and especially its
rhaetor marked this conversation as resolved.
Show resolved Hide resolved
xref:user-guide/create-project.adoc#dependency-management[Dependency management] section
for more information about writing applications with {quarkus-cxf-project-name}.
====
Expand Down
4 changes: 2 additions & 2 deletions ...modules/ROOT/pages/reference/extensions/quarkus-cxf-rt-transports-http-hc5.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ or add these coordinates to your existing project:
ifeval::[{doc-show-user-guide-link} == true]
[TIP]
====
Check the xref:user-guide/index.adoc[User guide] and especially its
Check the xref:user-guide/index.adoc#user-guide-index[User guide] and especially its
xref:user-guide/create-project.adoc#dependency-management[Dependency management] section
for more information about writing applications with {quarkus-cxf-project-name}.
====
Expand Down Expand Up @@ -67,7 +67,7 @@ in the source tree of {quarkus-cxf-project-name}
include::example$hc5/async-binding.xml[]
----

This file should then be passed to xref:user-guide/contract-first-code-first/generate-java-from-wsdl.adoc[wsdl2java]
This file should then be passed to xref:user-guide/contract-first-code-first/generate-java-from-wsdl.adoc#generate-java-from-wsdl[wsdl2java]
rhaetor marked this conversation as resolved.
Show resolved Hide resolved
through its xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus-cxf-codegen-wsdl2java-additional-params[additional-params] property:

.application.properties
Expand Down
2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/reference/extensions/quarkus-cxf-rt-ws-rm.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ or add these coordinates to your existing project:
ifeval::[{doc-show-user-guide-link} == true]
[TIP]
====
Check the xref:user-guide/index.adoc[User guide] and especially its
Check the xref:user-guide/index.adoc#user-guide-index[User guide] and especially its
xref:user-guide/create-project.adoc#dependency-management[Dependency management] section
for more information about writing applications with {quarkus-cxf-project-name}.
====
Expand Down
Loading