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

[MNG-8029] improve documentation about mirror settings #1395

Merged
merged 1 commit into from
Feb 17, 2024
Merged

[MNG-8029] improve documentation about mirror settings #1395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
5 changes: 0 additions & 5 deletions apache-maven/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,4 @@ under the License.
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0 http://maven.apache.org/xsd/decoration-1.8.0.xsd">

<edit>${project.scm.url}</edit>

<body>
<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
3 changes: 0 additions & 3 deletions maven-artifact/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,5 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
3 changes: 0 additions & 3 deletions maven-builder-support/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,5 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
3 changes: 0 additions & 3 deletions maven-compat/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,5 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
13 changes: 7 additions & 6 deletions maven-core/src/main/java/org/apache/maven/bridge/MavenRepositorySystem.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@

/**
* @author Jason van Zyl
* @since 3.2.3
*/
@Component(role = MavenRepositorySystem.class, hint = "default")
public class MavenRepositorySystem {
Expand Down Expand Up @@ -677,15 +678,15 @@ public static Mirror getMirror(ArtifactRepository repository, List<Mirror> mirro
/**
* This method checks if the pattern matches the originalRepository. Valid patterns:
* <ul>
* <li>{@code *} = everything,</li>
* <li>{@code external:*} = everything not on the localhost and not file based,</li>
* <li>{@code external:http:*} = any repository not on the localhost using HTTP,</li>
* <li>{@code repo,repo1} = {@code repo} or {@code repo1},</li>
* <li>{@code *,!repo1} = everything except {@code repo1}.</li>
* <li>{@code *} (since 2.0.5)= everything,</li>
* <li>{@code external:*} (since 2.0.9)= everything not on the localhost and not file based,</li>
* <li>{@code external:http:*} (since 3.8.0)= any repository not on the localhost using HTTP,</li>
* <li>{@code repo,repo1} (since 2.0.9)= {@code repo} or {@code repo1},</li>
* <li>{@code *,!repo1} (since 2.0.9)= everything except {@code repo1}.</li>
* </ul>
*
* @param originalRepository to compare for a match.
* @param pattern used for match. Currently only '*' is supported.
* @param pattern used for match.
* @return true if the repository is a match to this pattern.
*/
static boolean matchPattern(ArtifactRepository originalRepository, String pattern) {
Expand Down
6 changes: 0 additions & 6 deletions maven-core/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,7 @@ under the License.
</menu>

<menu name="Reference">
<item name="Lifecycles" href="lifecycles.html"/>
<item name="Plugin Bindings to Default Lifecycle" href="default-bindings.html"/>
<item name="Artifact Handlers" href="artifact-handlers.html"/>
<item name="Core Extensions" href="core-extensions.html"/>
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
7 changes: 0 additions & 7 deletions maven-embedder/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,5 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu name="Reference">
<item name="CLI options" href="cli.html"/>
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
7 changes: 0 additions & 7 deletions maven-model-builder/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,5 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu name="Reference">
<item name="Super POM" href="super-pom.html"/>
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
3 changes: 0 additions & 3 deletions maven-model/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,5 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
3 changes: 0 additions & 3 deletions maven-plugin-api/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,5 @@
<item name="META-INF/maven/lifecycle.xml" href="lifecycle-mappings.html"/>
<item name="META-INF/maven/plugin.xml" href="plugin.html"/>
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
3 changes: 0 additions & 3 deletions maven-repository-metadata/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,5 @@ under the License.
<!--item name="Source Xref" href="xref/index.html"/-->
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
3 changes: 0 additions & 3 deletions maven-resolver-provider/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,5 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
3 changes: 0 additions & 3 deletions maven-settings-builder/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,5 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
37 changes: 27 additions & 10 deletions maven-settings/src/main/mdo/settings.mdo
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,9 @@
<description>
<![CDATA[
<p>This is a reference for the user-specific configuration for Maven.</p>
<p>Includes things that should not be distributed with the pom.xml file, such as developer identity, along with
<p>Includes things that should not be distributed with the <code>pom.xml</code> file, such as developer identity, along with
local settings, like proxy information.</p>
<p>The default location for the settings file is <i>~/.m2/settings.xml</i></p>
<p>The default location for the user settings file is <code>~/.m2/settings.xml</code></p>
]]>
</description>
<defaults>
Expand Down Expand Up @@ -99,6 +99,7 @@
<type>String</type>
<defaultValue>default</defaultValue>
<required>true</required>
<description>Item identifier.</description>
</field>
</fields>
</class>
Expand Down Expand Up @@ -137,7 +138,7 @@
<version>1.0.0+</version>
<description>
<![CDATA[
Whether Maven should use the plugin-registry.xml file to manage plugin versions.
Whether Maven should use the <code>plugin-registry.xml</code> file to manage plugin versions.
]]>
</description>
<type>boolean</type>
Expand Down Expand Up @@ -169,8 +170,8 @@
<version>1.0.0+</version>
<description><![CDATA[
Configuration for different java environment profiles. One good use
for this might be to configure both JDK 1.4 and JDK 1.5 to work with
maven. Profiles will allow switching of entire java environments
for this might be to configure both JDK 1.4 and JDK 5 to work with
Maven. Profiles will allow switching of entire java environments
based on the profile id, either in the defaults section below, or on
the command line.
]]></description>
Expand Down Expand Up @@ -495,7 +496,7 @@
<version>1.0.0+</version>
<description>
<![CDATA[
The list of non-proxied hosts (delimited by |).
The list of non-proxied hosts (delimited by <code>|</code>).
]]>
</description>
<type>String</type>
Expand Down Expand Up @@ -596,8 +597,12 @@
<version>1.0.0+</version>
<type>String</type>
<description>
The server ID of the repository being mirrored, e.g.,
"central". This MUST NOT match the mirror id.
<![CDATA[
A repository id or (since Maven 2.0.9) an expression matching one or many repository ids to mirror, e.g.,
<code>central</code> or <code>*,!repo1</code>.
<code>*</code> (since Maven 2.0.5), <code>external:*</code> (since Maven 2.0.9) and <code>external:http:*</code> (since Maven 3.8.0) have
a special meaning: see <a href="/guides/mini/guide-mirror-settings.html">Mirror Settings</a> guide.
]]>
</description>
</field>
<field>
Expand All @@ -621,16 +626,24 @@
<version>1.1.0+</version>
<type>String</type>
<defaultValue>default</defaultValue>
<description>The layout of the mirror repository. Since Maven 3.</description>
<description>
<![CDATA[
The layout of the mirror repository.
<br><b>Since</b>: Maven 3
Copy link
Contributor

Choose a reason for hiding this comment

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

Why not using @since Maven 3 instead ? (same for the other <br><b>Since</b>: Maven xxx pattern)

Copy link
Member Author

@hboutemy hboutemy Feb 2, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

because I just reused the existing pattern
I don't know if @since works with Modello xdoc, need to check: doing the pattern change in every .mdo could be a good thing for another PR (find . -name '*.mdo' -exec grep -H 'Since</b>' {} \; shows maven.mdo and settings.mdo in 3.9.x branch)

Copy link
Contributor

Choose a reason for hiding this comment

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

It clearly does not render very well. It would be nice if modello could be extended to understand javadoc syntax, as it's already used and is not displayed really nicely:
https://maven.apache.org/ref/4.0.0-alpha-12/maven-settings/settings.html#proxy

Copy link
Contributor

Choose a reason for hiding this comment

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

Maybe using a small library such as https://github.com/chhorz/javadoc-parser ?

Copy link
Contributor

Choose a reason for hiding this comment

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

codehaus-plexus/modello#414

Renders as
image
instead of
image

Copy link
Member Author

Choose a reason for hiding this comment

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

I'll merge this PR with the existing pattern
dropping the existing pattern to replace by better option is nice, but it's not the current objective: I'll be happy that the content is changed later

]]>
</description>
</field>
<field>
<name>mirrorOfLayouts</name>
<version>1.1.0+</version>
<type>String</type>
<defaultValue>default,legacy</defaultValue>
<description>
<![CDATA[
The layouts of repositories being mirrored. This value can be used to restrict the usage
of the mirror to repositories with a matching layout (apart from a matching id). Since Maven 3.
of the mirror to repositories with a matching layout (apart from a matching id).
<br><b>Since</b>: Maven 3
]]>
</description>
</field>
<field>
Expand All @@ -639,7 +652,11 @@
<type>boolean</type>
<defaultValue>false</defaultValue>
<description>
<![CDATA[
Whether this mirror should be blocked from any download request but fail the download process, explaining why.
<br><b>Default value is</b>: <code>false</code>
<br><b>Since</b>: Maven 3.8.0
]]>
</description>
</field>
</fields>
Expand Down
15 changes: 14 additions & 1 deletion maven-settings/src/site/apt/index.apt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@

Maven Settings Model

This is strictly the model for Maven settings.
This is strictly the model for Maven settings. All the effective settings building logic from multiple <<<settings.xml>>> files
is done in {{{../maven-settings-builder/}Maven Settings Builder}}.

The following are generated from this model:

Expand All @@ -34,3 +35,15 @@ Maven Settings Model
* A {{{./settings.html}Descriptor Reference}}

* An {{{https://maven.apache.org/xsd/settings-1.2.0.xsd}XSD}}

* See Also User Documentation

* {{{https://maven.apache.org/settings.html} Settings Reference}},

* {{{https://maven.apache.org/guides/mini/guide-mirror-settings.html} Mirror Settings}},

* {{{https://maven.apache.org/guides/mini/guide-deployment-security-settings.html} Security and Deployment Settings}},

* {{{https://maven.apache.org/guides/mini/guide-encryption.html} Password Encryption}},

* {{{https://maven.apache.org/guides/mini/guide-proxies.html} Configuring a proxy}}.
3 changes: 0 additions & 3 deletions maven-settings/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,5 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
3 changes: 0 additions & 3 deletions maven-slf4j-provider/src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,5 @@ under the License.
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>

<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>
11 changes: 6 additions & 5 deletions src/site/site.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,25 +46,26 @@ under the License.
<item name="Download" href="/download.html"/>
</menu>

<menu name="Descriptors Reference">
<menu inherit="bottom" name="Descriptors Reference">
<item name="POM" href="./maven-model/maven.html"/>
<item name="Settings" href="./maven-settings/settings.html"/>
<item name="Toolchains" href="./maven-core/toolchains.html"/>
</menu>

<menu name="Reference">
<menu inherit="bottom" name="Reference">
<item name="Lifecycles" href="./maven-core/lifecycles.html"/>
<item name="Plugin Bindings to Default Lifecycle" href="./maven-core/default-bindings.html"/>
<item name="Artifact Handlers" href="./maven-core/artifact-handlers.html"/>
<item name="CLI options" href="./maven-embedder/cli.html"/>
<item name="Super POM" href="./maven-model-builder/super-pom.html"/>
</menu>

<menu name="Development">
<menu inherit="bottom" name="Development">
<item name="Maven Developer Centre" href="../../developers/index.html"/>
<item name="Maven Core ITs" href="../../core-its/index.html"/>
</menu>

<menu ref="modules"/>
<menu ref="reports"/>
<menu inherit="bottom" ref="modules"/>
<menu inherit="bottom" ref="reports"/>
</body>
</project>
Loading