Skip to content

Commit 1e6626a

Browse files
poikilothermpoikilotherm
committed
feat(docs): add Maven site documentation and resources
- Introduce structured documentation for the Dataverse SPI Plugin API, including index, examples, and modules pages. - Add custom styles, site branding, and navigation for improved developer experience. - Configure Maven Site Plugin and reporting tools for streamlined site generation. - Include GitHub Actions workflow for automated site deployment to GitHub Pages.
1 parent 84e28a1 commit 1e6626a

12 files changed

Lines changed: 513 additions & 0 deletions

File tree

‎.github/workflows/site.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Publish Maven Site
2+
3+
on:
4+
push:
5+
# branches:
6+
# - main
7+
# workflow_dispatch:
8+
9+
permissions:
10+
contents: write
11+
12+
concurrency:
13+
group: publish-maven-site-${{ github.ref }}
14+
cancel-in-progress: true
15+
16+
jobs:
17+
publish-site:
18+
runs-on: ubuntu-latest
19+
20+
steps:
21+
- name: Check out source
22+
uses: actions/checkout@v6
23+
24+
- name: Set up Java 17
25+
uses: actions/setup-java@v5
26+
with:
27+
distribution: temurin
28+
java-version: '17'
29+
cache: maven
30+
31+
- name: Build and verify project site
32+
run: mvn -B verify site
33+
34+
- name: Add .nojekyll
35+
run: touch target/site/.nojekyll
36+
37+
- name: Deploy to gh-pages
38+
uses: JamesIves/github-pages-deploy-action@v4
39+
with:
40+
branch: gh-pages
41+
folder: target/site
42+
target-folder: snapshot
43+
clean: true
44+
single-commit: true

‎pom.xml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,22 @@
3838
</developer>
3939
</developers>
4040

41+
<licenses>
42+
<license>
43+
<name>${project.license.name}</name>
44+
<url>${project.license.url}</url>
45+
<distribution>repo</distribution>
46+
</license>
47+
</licenses>
48+
49+
<scm>
50+
<url>https://github.com/gdcc/dataverse-spi</url>
51+
</scm>
52+
4153
<properties>
4254
<jdk.version>17</jdk.version>
55+
<project.license.name>Apache License, Version 2.0</project.license.name>
56+
<project.license.url>https://www.apache.org/licenses/LICENSE-2.0.txt</project.license.url>
4357
</properties>
4458

4559
<dependencyManagement>
@@ -71,4 +85,104 @@
7185
</dependency>
7286
</dependencies>
7387

88+
<build>
89+
<plugins>
90+
<plugin>
91+
<groupId>org.apache.maven.plugins</groupId>
92+
<artifactId>maven-site-plugin</artifactId>
93+
<dependencies>
94+
<dependency>
95+
<groupId>org.sentrysoftware.maven</groupId>
96+
<artifactId>maven-skin-tools</artifactId>
97+
<version>1.7.00</version>
98+
</dependency>
99+
</dependencies>
100+
</plugin>
101+
</plugins>
102+
</build>
103+
104+
<reporting>
105+
<plugins>
106+
<plugin>
107+
<groupId>org.apache.maven.plugins</groupId>
108+
<artifactId>maven-javadoc-plugin</artifactId>
109+
<reportSets>
110+
<reportSet>
111+
<id>aggregate-javadocs</id>
112+
<!-- inherited=false means children do not do the same thing individually -->
113+
<inherited>false</inherited>
114+
<reports>
115+
<report>aggregate</report>
116+
</reports>
117+
</reportSet>
118+
</reportSets>
119+
<configuration>
120+
<show>protected</show>
121+
<!-- Remove after Javadocs -->
122+
<doclint>none</doclint>
123+
124+
<detectLinks>true</detectLinks>
125+
<failOnError>false</failOnError>
126+
<quiet>true</quiet>
127+
<source>${jdk.version}</source>
128+
129+
<doctitle>Dataverse SPI Plugin API Reference</doctitle>
130+
<windowtitle>Dataverse SPI Plugin API Reference</windowtitle>
131+
<addStylesheets>
132+
<addStylesheet>custom.css</addStylesheet>
133+
</addStylesheets>
134+
<!-- Create a banner on top of every page allowing to return to main docs page -->
135+
<top><![CDATA[
136+
<div class="top-nav-backlink">
137+
<a href="../index.html">← Back to Dataverse SPI Plugin API homepage</a>
138+
</div>
139+
]]></top>
140+
<bottom><![CDATA[
141+
<div>
142+
Version ${project.version} -&nbsp;
143+
Copyright by ${project.organization.name} -&nbsp;
144+
Licensed under <a href="${project.license.url}" target="_blank">${project.license.name}</a> |&nbsp;
145+
<a href="../index.html">Dataverse SPI Plugin API</a> |&nbsp;
146+
<a href="https://dataverse.org" target="_blank">The Dataverse Project</a>
147+
</div>
148+
]]></bottom>
149+
150+
<tags>
151+
<tag>
152+
<name>apiNote</name>
153+
<placement>a</placement>
154+
<head>API Note:</head>
155+
</tag>
156+
<tag>
157+
<name>implSpec</name>
158+
<placement>a</placement>
159+
<head>Implementation Requirements:</head>
160+
</tag>
161+
<tag>
162+
<name>implNote</name>
163+
<placement>a</placement>
164+
<head>Implementation Note:</head>
165+
</tag>
166+
</tags>
167+
</configuration>
168+
</plugin>
169+
170+
<plugin>
171+
<groupId>org.apache.maven.plugins</groupId>
172+
<artifactId>maven-project-info-reports-plugin</artifactId>
173+
<version>3.9.0</version>
174+
<reportSets>
175+
<reportSet>
176+
<id>root-project-info</id>
177+
<!-- inherited=false means children do not do the same thing individually -->
178+
<inherited>false</inherited>
179+
<reports>
180+
<report>team</report>
181+
</reports>
182+
</reportSet>
183+
</reportSets>
184+
</plugin>
185+
</plugins>
186+
</reporting>
187+
74188
</project>

‎src/main/javadoc/custom.css‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.top-nav-backlink {
2+
padding: 0.75rem 1rem;
3+
font-size: 1rem;
4+
font-weight: 600;
5+
}
6+
7+
.top-nav-backlink a {
8+
text-decoration: none;
9+
}
10+
11+
.top-nav-backlink a:hover {
12+
text-decoration: underline;
13+
}
14+
15+
.doc-version {
16+
margin-left: 1rem;
17+
color: #57606a;
18+
font-weight: 500;
19+
}

‎src/site/markdown/examples.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Examples
2+
3+
This page should contain practical examples for plugin authors.
4+
5+
## Suggested examples to add
6+
7+
- creating a minimal plugin
8+
- implementing a service provider
9+
- packaging and deployment
10+
- handling metadata or export extension points
11+
12+
## Documentation style
13+
14+
For each example, consider using this structure:
15+
16+
1. **Goal**
17+
2. **Prerequisites**
18+
3. **Code**
19+
4. **Explanation**
20+
5. **Related API links**
21+
22+
## API Reference
23+
24+
When relevant, link directly to classes in the [Javadocs](apidocs/index.html).

‎src/site/markdown/index.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Dataverse SPI Plugin API
2+
3+
This site provides documentation for the SPI (Service Provider Interface) module for Dataverse.
4+
5+
## Project Contents
6+
7+
This project offers a universal Java module to create plugins for Dataverse:
8+
9+
- It provides *API contracts* a plugin author implements to create a new plugin.
10+
- It provides an easy-to-use *annotation* `@DataversePlugin`, marking an implementation class as such a plugin.
11+
- It generates *plugin metadata* automatically to make a plugin author's life as convenient as possible.
12+
- It allows coordinated data exchange with the core using a *core provider* concept.
13+
- It helps the core to detect any plugins an administrator adds to their Dataverse installation and validate its compatibility.
14+
15+
## Audience
16+
17+
This documentation is intended for developers who want to:
18+
19+
- build Dataverse plugins
20+
- understand the available SPI contracts
21+
- explore integration points
22+
- browse the API reference
23+
24+
## Maven Coordinates
25+
26+
The (current) artifact is published as `io.gdcc:dataverse-spi` to *Maven Central*.
27+
Use it in Maven like this:
28+
29+
```xml
30+
<dependency>
31+
<groupId>io.gdcc</groupId>
32+
<artifactId>dataverse-spi</artifactId>
33+
<version>x.y.z</version>
34+
</dependency>
35+
```
36+
37+
Nnote: if you're using the GDCC Maven Parent, you may omit the version.
38+
39+
## Documentation
40+
41+
- [Examples](examples.html)
42+
- [Modules](modules.html)
43+
- [Javadocs](apidocs/index.html)
44+
45+
## License
46+
47+
Licensed under the same terms as the Dataverse core project: [${project.license.name}](${project.license.url}).
48+
49+
## Context & History
50+
51+
This module did not appear out of thin air.
52+
Before it was moved to this project with an independent release cycle and potential governance, it was part of the Dataverse core.
53+
54+
You can find the first ever commit that started it all here: [IQSS/dataverse@e560a34e](https://github.com/IQSS/dataverse/commit/e560a34e89b12a08b0e936e0cc8bd429f7a8c7c5).
55+
In an effort back in 2022, funded by DANS and undertaken by Jim Myers, this package originally formed as a separate Maven module.
56+
You can find the history and context in core pull request [IQSS/dataverse#9175](https://github.com/IQSS/dataverse/pull/9175).
57+
58+
In 2026, it was decided within the [Dataverse Core Dev Team](https://dataverse.org/about) to move the Maven module into a separate repository, enabling an independent release cycle, tags, the works.
59+
If you are interested in any commit history that happened before the initial Maven module creation, you can dig your way back from [IQSS/dataverse@fa0e2812](https://github.com/IQSS/dataverse/tree/fa0e28124a15b0db8042959b9fee536591f26f8d/modules/dataverse-spi)

‎src/site/markdown/modules.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Modules
2+
3+
This project is split into several Maven modules.
4+
5+
## api
6+
7+
Core API contracts intended for plugin developers.
8+
9+
## core
10+
11+
Shared core functionality supporting the SPI-based extension model.
12+
13+
## export
14+
15+
Types related to export-oriented extension points.
16+
17+
## meta
18+
19+
Metadata-related SPI support.
20+
21+
## How to choose
22+
23+
Start with the module that exposes the contract you need, then use the [Javadocs](apidocs/index.html) to inspect the types in detail.

‎src/site/resources/images/dataverse-logo.png‎

4.69 KB
Loading

‎src/site/resources/images/gdcc-logo.png‎

5.13 KB
Loading

‎src/site/resources/images/project-logo-editable.svg‎

Lines changed: 92 additions & 0 deletions
Loading

‎src/site/resources/images/project-logo.png‎

19.5 KB
Loading

0 commit comments

Comments
 (0)