Skip to content

Commit cf1e65f

Browse files
martinbonninmartinbonnin
authored
Improve docs (#224)
1 parent 8839a38 commit cf1e65f

17 files changed

Lines changed: 7919 additions & 151 deletions

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
.vscode
2+
dist
3+
node_modules
4+
.astro
15
.idea
26
.gradle
37
build

‎README.md‎

Lines changed: 11 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -1,157 +1,18 @@
1-
_New accounts created after March 12th 2024 are configured to use the new publishing by default and can use this plugin._
1+
[![Slack](https://img.shields.io/static/v1?label=gradle-community&message=gradleup&color=A97BFF&logo=slack&style=flat-square)](https://gradle-community.slack.com/archives/C07GJEMUZDH)
22

3-
_If your account was created before March 12th 2024, you'll need to either [migrate to the central portal publisher API](https://central.sonatype.org/faq/what-is-different-between-central-portal-and-legacy-ossrh/#process-to-migrate) or [update your url to the Portal OSSRH staging API url](https://central.sonatype.org/publish/publish-portal-ossrh-staging-api/)._
3+
[![Maven Central](https://img.shields.io/maven-central/v/com.gradleup.nmcp/nmcp?style=flat-square)](https://central.sonatype.com/namespace/com.gradleup.nmcp)
4+
[![Maven Snapshots](https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fcentral.sonatype.com%2Frepository%2Fmaven-snapshots%2Fcom%2Fgradleup%2Fnmcp%2Fnmcp%2Fmaven-metadata.xml&style=flat-square&label=snapshots&color=%2315252D&strategy=latestProperty)](https://central.sonatype.com/repository/maven-snapshots/com/gradleup/nmcp)
45

5-
_The date for [OSSRH sunsetting](https://central.sonatype.org/news/20250326_ossrh_sunset/) was June, 30th 2025. The service is now [EOL](https://central.sonatype.org/pages/ossrh-eol/)._
6+
</div>
67

7-
---
8+
## 📦 Nmcp
89

9-
# Nmcp: New Maven Central Publishing
10+
Your Central Portal publishing companion.
1011

11-
A plugin that uses the new [Central Portal publisher API](https://central.sonatype.org/publish/publish-portal-api/) to publish existing publications to Maven Central.
12+
## 📚 Documentation
1213

13-
> [!WARNING]
14-
> Nmcp does **not** create publications or apply the `maven-publish` plugin. This must be done using other means. Nmcp uses existing publications, stages them locally and uploads a zip to the Central Portal publisher API.
15-
>
16-
> For a higher level API use [vanniktech/gradle-maven-publish-plugin](https://github.com/vanniktech/gradle-maven-publish-plugin/).
14+
See the project website for documentation:<br/>
15+
[https://gradleup.github.io/nmcp/](https://gradleup.github.io/nmcp/)
1716

18-
# QuickStart
19-
20-
Configure `nmcp` in your root project using the quick way:
21-
22-
```kotlin
23-
// root/build.gradle[.kts]
24-
plugins {
25-
id("com.gradleup.nmcp.aggregation").version("1.3.0")
26-
}
27-
28-
nmcpAggregation {
29-
centralPortal {
30-
username = TODO("Create a token username at https://central.sonatype.com/")
31-
password = TODO("Create a token password at https://central.sonatype.com/")
32-
// publish manually from the portal
33-
publishingType = "USER_MANAGED"
34-
// or if you want to publish automatically
35-
publishingType = "AUTOMATIC"
36-
}
37-
38-
// Publish all projects that apply the 'maven-publish' plugin
39-
publishAllProjectsProbablyBreakingProjectIsolation()
40-
}
41-
```
42-
43-
Call `publishAggregationToCentralPortal` to publish the aggregation:
44-
45-
```bash
46-
./gradlew publishAggregationToCentralPortal
47-
# yay everything is uploaded 🎉
48-
# go to https://central.sonatype.com/ to release if you used USER_MANAGED
49-
```
50-
51-
Call `publishAggregationToCentralPortalSnapshots` to publish to the snapshots:
52-
53-
```bash
54-
./gradlew publishAggregationToCentralPortalSnapshots
55-
# yay everything is uploaded to "https://central.sonatype.com/repository/maven-snapshots/" 🎉
56-
```
57-
58-
# Project isolation compatible version
59-
60-
`publishAllProjectsProbablyBreakingProjectIsolation()` uses the `allprojects {}` block and is incompatible with [Project-isolation](https://gradle.github.io/configuration-cache/).
61-
62-
You can be 100% compatible by adding the plugin to each module you want to publish:
63-
64-
```kotlin
65-
//root/module/build.gradle.kts
66-
plugins {
67-
id("com.gradleup.nmcp").version("1.3.0")
68-
}
69-
```
70-
71-
And then list all modules in your root project:
72-
73-
```kotlin
74-
//root/build.gradle.kts
75-
plugins {
76-
id("com.gradleup.nmcp.aggregation").version("1.3.0")
77-
}
78-
79-
nmcpAggregation {
80-
centralPortal {
81-
username = TODO("Create a token username at https://central.sonatype.com/")
82-
password = TODO("Create a token password at https://central.sonatype.com/")
83-
publishingType = "USER_MANAGED"
84-
}
85-
}
86-
87-
dependencies {
88-
// Add all dependencies here
89-
nmcpAggregation(project(":module1"))
90-
nmcpAggregation(project(":module2"))
91-
nmcpAggregation(project(":module3"))
92-
}
93-
```
94-
95-
Call `publishAggregationToCentralPortal` to publish the aggregation:
96-
97-
```bash
98-
./gradlew publishAggregationToCentralPortal
99-
# yay everything is uploaded 🎉
100-
# go to https://central.sonatype.com/ to release if you used USER_MANAGED
101-
```
102-
103-
Call `publishAggregationToCentralPortalSnapshots` to publish to the snapshots:
104-
105-
```bash
106-
./gradlew publishAggregationToCentralPortalSnapshots
107-
# yay everything is uploaded to "https://central.sonatype.com/repository/maven-snapshots/" 🎉
108-
```
109-
110-
# All options
111-
112-
```kotlin
113-
// root/build.gradle[.kts]
114-
nmcpAggregation {
115-
centralPortal {
116-
// publish manually from the portal
117-
publishingType = "USER_MANAGED"
118-
119-
// Increase the validation timeout to 30 minutes
120-
validationTimeout = java.time.Duration.of(30, ChronoUnit.MINUTES)
121-
// Disable waiting for validation
122-
validationTimeout = java.time.Duration.ZERO
123-
124-
// Publish automatically once validation is successful
125-
publishingType = "AUTOMATIC"
126-
127-
// Increase the publishing timeout to 30 minutes
128-
publishingTimeout = java.time.Duration.of(30, ChronoUnit.MINUTES)
129-
// Disable waiting for publishing
130-
publishingTimeout = java.time.Duration.ZERO
131-
132-
// Customize the publication name
133-
publicationName = "My Awesome Library version $version"
134-
135-
// send publications one after the other instead of in parallel (might be slower)
136-
uploadSnapshotsParallelism.set(1)
137-
}
138-
}
139-
```
140-
141-
# Inspect the deployment content
142-
143-
The `nmcpZipAggregation` task is an intermediate task of `publishAggregationToCentralPortal` that generates the ZIP file that is then sent to Maven Central.
144-
You can use this task to inspect the entire content before publishing your project.
145-
146-
```bash
147-
./gradlew nmcpZipAggregation
148-
# go to build/nmcp/zip/aggregation.zip
149-
```
150-
151-
# Requirements
152-
153-
Nmcp requires Java 17+, Gradle 8.8+ for the settings plugin and Gradle 8.2+ otherwise.
154-
155-
# KDoc
156-
157-
The API reference is available at https://gradleup.com/nmcp/kdoc/nmcp/index.html
17+
The Kdoc API reference can be found at:<br/>
18+
[https://gradleup.github.io/nmcp/kdoc](https://gradleup.github.io/nmcp/kdoc)

‎build.gradle.kts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,29 @@ plugins {
1111
}
1212

1313
Librarian.root(project)
14+
15+
tasks.register("docsNpmInstall", Exec::class.java) {
16+
enabled = file("docs").exists()
17+
18+
commandLine("npm", "ci")
19+
workingDir("docs")
20+
}
21+
22+
tasks.register("docsNpmBuild", Exec::class.java) {
23+
dependsOn("docsNpmInstall")
24+
25+
enabled = file("docs").exists()
26+
27+
commandLine("npm", "run", "build")
28+
workingDir("docs")
29+
}
30+
31+
tasks.named("librarianStaticContent").configure {
32+
dependsOn("docsNpmBuild")
33+
34+
val from = file("docs/dist")
35+
doLast {
36+
from.copyRecursively(outputs.files.single(), overwrite = true)
37+
}
38+
}
39+

‎docs/README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Starlight Starter Kit: Basics
2+
3+
[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
4+
5+
```
6+
npm create astro@latest -- --template starlight
7+
```
8+
9+
[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
10+
[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
11+
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/withastro/starlight&create_from_path=examples/basics)
12+
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs)
13+
14+
> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
15+
16+
## 🚀 Project Structure
17+
18+
Inside of your Astro + Starlight project, you'll see the following folders and files:
19+
20+
```
21+
.
22+
├── public/
23+
├── src/
24+
│ ├── assets/
25+
│ ├── content/
26+
│ │ ├── docs/
27+
│ └── content.config.ts
28+
├── astro.config.mjs
29+
├── package.json
30+
└── tsconfig.json
31+
```
32+
33+
Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
34+
35+
Images can be added to `src/assets/` and embedded in Markdown with a relative link.
36+
37+
Static assets, like favicons, can be placed in the `public/` directory.
38+
39+
## 🧞 Commands
40+
41+
All commands are run from the root of the project, from a terminal:
42+
43+
| Command | Action |
44+
| :------------------------ | :----------------------------------------------- |
45+
| `npm install` | Installs dependencies |
46+
| `npm run dev` | Starts local dev server at `localhost:4321` |
47+
| `npm run build` | Build your production site to `./dist/` |
48+
| `npm run preview` | Preview your build locally, before deploying |
49+
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
50+
| `npm run astro -- --help` | Get help using the Astro CLI |
51+
52+
## 👀 Want to learn more?
53+
54+
Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).

‎docs/astro.config.mjs‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// @ts-check
2+
import { defineConfig } from 'astro/config';
3+
import starlight from '@astrojs/starlight';
4+
5+
export default defineConfig({
6+
site: 'https://gradleup.com',
7+
base: '/nmcp',
8+
integrations: [
9+
starlight({
10+
title: 'Nmcp',
11+
editLink: {
12+
baseUrl: 'https://github.com/GradleUp/nmcp/edit/main/docs/',
13+
},
14+
logo: {
15+
src: './src/assets/logo.svg'
16+
},
17+
social: {
18+
github: 'https://github.com/GradleUp/nmcp',
19+
},
20+
sidebar: [
21+
{ label: 'Quickstart', link: '/', },
22+
{ label: 'Manual configuration', link: '/manual-configuration' },
23+
{ label: 'Debugging', link: '/debugging' },
24+
{ label: 'Maven Central FAQ', link: '/portal-faq' },
25+
{ label: 'Programmatic API', link: '/programmatic-api' },
26+
{ label: 'KDoc', link: 'https://gradleup.com/nmcp/kdoc/nmcp/index.html ' },
27+
],
28+
}),
29+
],
30+
});

0 commit comments

Comments
 (0)