Starting point
This commit is contained in:
Dave Syer
15
spring-grpc-docs/src/assembly/javadocs.xml
Normal file
15
spring-grpc-docs/src/assembly/javadocs.xml
Normal file
@@ -0,0 +1,15 @@
|
||||
<assembly xmlns="http://maven.apache.org/ASSEMBLY/2.1.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/2.1.0 http://maven.apache.org/xsd/assembly-2.1.0.xsd">
|
||||
<id>docs</id>
|
||||
<formats>
|
||||
<format>zip</format>
|
||||
</formats>
|
||||
<includeBaseDirectory>false</includeBaseDirectory>
|
||||
<fileSets>
|
||||
<fileSet>
|
||||
<directory>../target/site/apidocs</directory>
|
||||
<outputDirectory>api</outputDirectory>
|
||||
</fileSet>
|
||||
</fileSets>
|
||||
</assembly>
|
||||
39
spring-grpc-docs/src/main/antora/antora-playbook.yml
Normal file
39
spring-grpc-docs/src/main/antora/antora-playbook.yml
Normal file
@@ -0,0 +1,39 @@
|
||||
# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2
|
||||
#
|
||||
# The purpose of this Antora playbook is to build the docs in the current branch.
|
||||
antora:
|
||||
extensions:
|
||||
- '@antora/collector-extension'
|
||||
- require: '@springio/antora-extensions/root-component-extension'
|
||||
root_component_name: 'grpc'
|
||||
site:
|
||||
title: Spring Grpc Reference
|
||||
url: https://docs.spring.io/spring-grpc/reference
|
||||
content:
|
||||
sources:
|
||||
- url: ./../../../..
|
||||
branches: HEAD
|
||||
start_path: spring-grpc-docs/src/main/antora
|
||||
worktrees: true
|
||||
asciidoc:
|
||||
attributes:
|
||||
page-pagination: ''
|
||||
hide-uri-scheme: '@'
|
||||
tabs-sync-option: '@'
|
||||
chomp: 'all'
|
||||
stem: 'asciimath'
|
||||
extensions:
|
||||
- '@asciidoctor/tabs'
|
||||
- '@springio/asciidoctor-extensions'
|
||||
- '@djencks/asciidoctor-mathjax'
|
||||
sourcemap: true
|
||||
urls:
|
||||
latest_version_segment: ''
|
||||
runtime:
|
||||
log:
|
||||
failure_level: warn
|
||||
format: pretty
|
||||
ui:
|
||||
bundle:
|
||||
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.6/ui-bundle.zip
|
||||
snapshot: true
|
||||
12
spring-grpc-docs/src/main/antora/antora.yml
Normal file
12
spring-grpc-docs/src/main/antora/antora.yml
Normal file
@@ -0,0 +1,12 @@
|
||||
name: grpc
|
||||
version: true
|
||||
title: Spring Grpc
|
||||
nav:
|
||||
- modules/ROOT/nav.adoc
|
||||
ext:
|
||||
collector:
|
||||
- run:
|
||||
command: mvnw process-resources
|
||||
local: true
|
||||
scan:
|
||||
dir: spring-grpc-docs/target/classes/antora-resources
|
||||
6
spring-grpc-docs/src/main/antora/modules/ROOT/nav.adoc
Normal file
6
spring-grpc-docs/src/main/antora/modules/ROOT/nav.adoc
Normal file
@@ -0,0 +1,6 @@
|
||||
* xref:index.adoc[Overview]
|
||||
* xref:concepts.adoc[Grpc Concepts]
|
||||
* xref:getting-started.adoc[Getting Started]
|
||||
|
||||
* xref:contribution-guidelines.adoc[Contribution Guidelines]
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
[[concepts]]
|
||||
= Grpc Concepts
|
||||
|
||||
This section describes core concepts that Spring Grpc uses. We recommend reading it closely to understand the ideas behind how Spring Grpc is implemented.
|
||||
@@ -0,0 +1,36 @@
|
||||
[[contribution-guidelines]]
|
||||
= Contribution Guidelines
|
||||
|
||||
== Code Formatting and Javadoc
|
||||
|
||||
Before submitting a PR, please run the following commands to ensure proper formatting and Javadoc processing
|
||||
|
||||
```
|
||||
./mvnw spring-javaformat:apply javadoc:javadoc -Pjavadoc
|
||||
```
|
||||
|
||||
The `-Pjavadoc` is a profile that enables Javadoc processing so as to avoid a long build time when developing.
|
||||
|
||||
== Contributing a New Grpc Model Implementation
|
||||
|
||||
This section outlines the steps for contributing a new Grpc model implementation.
|
||||
Grpc models vary significantly, with diverse inputs and outputs -- from chat models that
|
||||
translate text input into text output, to text-to-image models that generate images
|
||||
from text descriptions.
|
||||
Complex models may even handle multiple types of input and output, such as combining text,
|
||||
images, and videos to produce mixed media output.
|
||||
|
||||
To contribute a new feature, adhere to the following steps:
|
||||
|
||||
. *Implement Auto-Configuration and a Spring Boot Starter*: This step involves creating the
|
||||
necessary auto-configuration and Spring Boot Starter to easily instantiate the new model with
|
||||
Spring Boot applications.
|
||||
|
||||
. *Write Tests*: All new classes should be accompanied by comprehensive tests.
|
||||
Existing tests can serve as a useful reference for structuring and implementing your tests.
|
||||
|
||||
. *Document Your Contribution*: Ensure your documentation follows the existing format,
|
||||
using the `spring-javaformat` plugin to format your code and Javadoc comments.
|
||||
|
||||
By following these guidelines, we can greatly expand the framework's range of supported models
|
||||
while following a common implementation and documentation pattern.
|
||||
@@ -0,0 +1,89 @@
|
||||
[[getting-started]]
|
||||
= Getting Started
|
||||
|
||||
This section offers jumping off points for how to get started using Spring Grpc.
|
||||
|
||||
You should follow the steps in each of the following section according to your needs.
|
||||
|
||||
NOTE: Spring Grpc supports Spring Boot 3.3.x
|
||||
|
||||
[[repositories]]
|
||||
== Add Milestone and Snapshot Repositories
|
||||
|
||||
If you prefer to add the dependency snippets by hand, follow the directions in the following sections.
|
||||
|
||||
To use the Milestone and Snapshot version, you need to add references to the Spring Milestone and/or Snapshot repositories in your build file.
|
||||
|
||||
For Maven, add the following repository definitions as needed:
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>spring-milestones</id>
|
||||
<name>Spring Milestones</name>
|
||||
<url>https://repo.spring.io/milestone</url>
|
||||
<snapshots>
|
||||
<enabled>false</enabled>
|
||||
</snapshots>
|
||||
</repository>
|
||||
<repository>
|
||||
<id>spring-snapshots</id>
|
||||
<name>Spring Snapshots</name>
|
||||
<url>https://repo.spring.io/snapshot</url>
|
||||
<releases>
|
||||
<enabled>false</enabled>
|
||||
</releases>
|
||||
</repository>
|
||||
</repositories>
|
||||
----
|
||||
|
||||
For Gradle, add the following repository definitions as needed:
|
||||
|
||||
[source,groovy]
|
||||
----
|
||||
repositories {
|
||||
mavenCentral()
|
||||
maven { url 'https://repo.spring.io/milestone' }
|
||||
maven { url 'https://repo.spring.io/snapshot' }
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
[[dependency-management]]
|
||||
== Dependency Management
|
||||
|
||||
The Spring Grpc Bill of Materials (BOM) declares the recommended versions of all the dependencies used by a given release of Spring Grpc.
|
||||
Using the BOM from your application’s build script avoids the need for you to specify and maintain the dependency versions yourself.
|
||||
Instead, the version of the BOM you’re using determines the utilized dependency versions.
|
||||
It also ensures that you’re using supported and tested versions of the dependencies by default, unless you choose to override them.
|
||||
|
||||
If you’re a Maven user, you can use the BOM by adding the following to your pom.xml file -
|
||||
|
||||
[source,xml]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-grpc-bom</artifactId>
|
||||
<version>1.0.0-SNAPSHOT</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
|
||||
Gradle users can also use the Spring Grpc BOM by leveraging Gradle (5.0+) native support for declaring dependency constraints using a Maven BOM.
|
||||
This is implemented by adding a 'platform' dependency handler method to the dependencies section of your Gradle build script.
|
||||
As shown in the snippet below this can then be followed by version-less declarations of the Starter Dependencies for the one or more spring-grpc modules you wish to use, e.g. spring-grpc-openai.
|
||||
|
||||
[source,gradle]
|
||||
----
|
||||
dependencies {
|
||||
implementation platform("org.springframework.ai:spring-grpc-bom:1.0.0-SNAPSHOT")
|
||||
// Replace the following with the starter dependencies of specific modules you wish to use
|
||||
implementation 'org.springframework.ai:spring-grpc-openai'
|
||||
}
|
||||
----
|
||||
@@ -0,0 +1,9 @@
|
||||
[[introduction]]
|
||||
= Spring Grpc
|
||||
|
||||
The `Spring Grpc` project aims to streamline the development of Grpc applications.
|
||||
|
||||
The xref:concepts.adoc[concepts section] provides a high-level overview of Grpc concepts and their representation in Spring Grpc.
|
||||
|
||||
The xref:getting-started.adoc[Getting Started] section shows you how to create your first Grpc application.
|
||||
Subsequent sections delve into each component and common use cases with a code-focused approach.
|
||||
@@ -0,0 +1,2 @@
|
||||
version: ${antora-component.version}
|
||||
prerelease: ${antora-component.prerelease}
|
||||
17
spring-grpc-docs/src/main/javadoc/overview.html
Normal file
17
spring-grpc-docs/src/main/javadoc/overview.html
Normal file
@@ -0,0 +1,17 @@
|
||||
<html>
|
||||
<body>
|
||||
<p>
|
||||
This document is the API specification for <a href="https://docs.spring.io/spring-grpc/reference" target="_top">Spring Grpc</a>
|
||||
</p>
|
||||
<div id="overviewBody">
|
||||
<p>
|
||||
For further API reference and developer documentation, see the
|
||||
<a href="https://docs.spring.io/spring-grpc/reference/" target="_top">
|
||||
Spring Grpc reference documentation</a>.
|
||||
That documentation contains more detailed, developer-targeted
|
||||
descriptions, with conceptual overviews, definitions of terms,
|
||||
and working code examples.
|
||||
</p>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user