Skip to content

Commit c5771cd

Browse files
TBXarkTBXark
committed
feat: 更新文档结构和内容，添加新指南和组件说明
1 parent daff5cf commit c5771cd

31 files changed

+367
-159
lines changed

‎content/_index.md‎

Lines changed: 50 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,55 @@
1-
Sphere
21
---
2+
title: Sphere
3+
layout: hextra-home
4+
---
5+
6+
{{< hextra/hero-badge >}}
7+
<div class="hx:w-2 hx:h-2 hx:rounded-full hx:bg-primary-400"></div>
8+
<span>Free, open source</span>
9+
{{< icon name="arrow-circle-right" attributes="height=14" >}}
10+
{{< /hextra/hero-badge >}}
11+
12+
<div class="hx:mt-6 hx:mb-6">
13+
{{< hextra/hero-headline >}}
14+
Build pragmatic Go backends&nbsp;<br class="hx:sm:block hx:hidden" />with Sphere
15+
{{< /hextra/hero-headline >}}
16+
</div>
317

4-
**Sphere** is a pragmatic Go backend toolkit centered around a clean monolithic template and a small toolchain that automates the boring parts: schema, API contracts, server stubs, Swagger, and even TypeScript clients. Start simple, scale when needed.
18+
<div class="hx:mb-12">
19+
{{< hextra/hero-subtitle >}}
20+
Monolithic-first toolkit with codegen for contracts, errors, stubs, and clients
21+
{{< /hextra/hero-subtitle >}}
22+
</div>
523

6-
- Core: `sphere`
7-
- Template: `sphere-layout`
8-
- Toolchain:
9-
- `sphere-cli`
10-
- `protoc-gen-sphere`
11-
- `protoc-gen-route`
12-
- `protoc-gen-sphere-binding`
13-
- `protoc-gen-sphere-errors`
24+
<div class="hx:mb-6">
25+
{{< hextra/hero-button text="Get Started" link="docs/getting-started" >}}
26+
</div>
1427

15-
What you build:
16-
- Define entities with Ent and APIs with Protobuf
17-
- Generate Go handlers, Swagger, error types, and client SDKs
18-
- Compose services with Gin + Wire; deploy as a single binary
28+
<div class="hx:mt-6"></div>
1929

20-
[Get started in the docs](./docs/)
30+
{{< hextra/feature-grid >}}
31+
{{< hextra/feature-card
32+
title="Contracts First"
33+
subtitle="Define APIs in Protobuf and entities in Ent; generate Go handlers, routers, bindings, and clients."
34+
>}}
35+
{{< hextra/feature-card
36+
title="Monolith-First Template"
37+
subtitle="Start with a single binary using Gin + Wire; evolve to multi-service when needed."
38+
>}}
39+
{{< hextra/feature-card
40+
title="Code Generation"
41+
subtitle="protoc-gen-sphere, protoc-gen-route, protoc-gen-sphere-binding, and protoc-gen-sphere-errors automate server, routing, tags, and typed errors."
42+
>}}
43+
{{< hextra/feature-card
44+
title="Typed Errors"
45+
subtitle="Define error enums in .proto; get consistent HTTP JSON with status, code, reason, and message."
46+
>}}
47+
{{< hextra/feature-card
48+
title="Swagger & Clients"
49+
subtitle="Generate OpenAPI from contracts and optional TypeScript SDKs for frontends."
50+
>}}
51+
{{< hextra/feature-card
52+
title="CLI & Layout"
53+
subtitle="sphere-cli and sphere-layout bootstrap projects with Makefile workflows and a sane project structure."
54+
>}}
55+
{{< /hextra/feature-grid >}}

‎content/docs/_index.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,13 @@ title: Docs
33
weight: 10
44
---
55

6-
Browse the Go Sphere documentation using the sidebar.
6+
Explore the Sphere documentation by section.
77

8+
<!--more-->
9+
10+
{{< cards >}}
11+
{{< card link="getting-started" title="Getting Started" icon="sparkles" >}}
12+
{{< card link="concepts" title="Core Concepts" icon="chart-square-bar" >}}
13+
{{< card link="components" title="Components" icon="template" >}}
14+
{{< card link="guides" title="Guides" icon="document-duplicate" >}}
15+
{{< /cards >}}

‎content/docs/components/_index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Components
3+
weight: 30
4+
---
5+
6+
Explore Sphere’s building blocks and repositories.
7+
8+
<!--more-->
9+
10+
{{< cards >}}
11+
{{< card link="core" title="Core" icon="adjustments" >}}
12+
{{< card link="cli" title="CLI" icon="document-duplicate" >}}
13+
{{< card link="generators" title="Generators" icon="sparkles" >}}
14+
{{< /cards >}}

‎content/docs/components/cli/_index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: CLI
3+
weight: 10
4+
---
5+
6+
Command-line tools to bootstrap and operate Sphere projects.
7+
8+
<!--more-->
9+
10+
{{< cards >}}
11+
{{< card link="sphere-cli" title="Sphere CLI" icon="document-duplicate" >}}
12+
{{< /cards >}}
13+

content/docs/toolchain/cli/sphere-cli.md renamed to content/docs/components/cli/sphere-cli.md

File renamed without changes.

content/docs/core/core-repos.md renamed to content/docs/components/core.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,19 @@
11
---
2-
title: Core Repos
2+
title: Core
33
weight: 10
44
---
55

6-
Sphere Core
6+
Sphere Core repositories and what they provide.
7+
8+
Core Repos
79
- `sphere`: multi-server application template with Gin utilities, docs/debug servers, middleware, and helpers
810
- Repo: https://github.com/go-sphere/sphere
911
- Provides `ginx` helpers like `WithJson`, `AbortWithJsonError`, `DataResponse`, `ErrorResponse`
1012
- `sphere-layout`: standard project layout and Makefile-driven workflow
1113
- Repo: https://github.com/go-sphere/sphere-layout
1214
- Includes buf configs, Swagger generation, TypeScript SDK generation, and examples of `sphere` usage
1315

14-
Use `sphere-cli create` to start from the `sphere-layout` template, then extend with your schema and APIs.
15-
16+
Getting Started
17+
- Install CLI: `go install github.com/go-sphere/sphere-cli@latest`
18+
- Create a project from the layout template: `sphere-cli create --name <project-name> [--module <go-module-name>]`
19+
- Extend with your schema and APIs; generate servers/bindings with the Sphere generators in this section

‎content/docs/components/generators/_index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Generators
3+
weight: 20
4+
---
5+
6+
Protobuf-centric generators that produce handlers, bindings, routing glue, and typed errors.
7+
8+
<!--more-->
9+
10+
{{< cards >}}
11+
{{< card link="protoc-gen-sphere" title="protoc-gen-sphere" icon="sparkles" >}}
12+
{{< card link="protoc-gen-route" title="protoc-gen-route" icon="template" >}}
13+
{{< card link="protoc-gen-sphere-binding" title="protoc-gen-sphere-binding" icon="document-duplicate" >}}
14+
{{< card link="protoc-gen-sphere-errors" title="protoc-gen-sphere-errors" icon="variable" >}}
15+
{{< /cards >}}
16+

content/docs/toolchain/generators/protoc-gen-route.md renamed to content/docs/components/generators/protoc-gen-route.md

File renamed without changes.

content/docs/toolchain/generators/protoc-gen-sphere-binding.md renamed to content/docs/components/generators/protoc-gen-sphere-binding.md

File renamed without changes.

content/docs/toolchain/generators/protoc-gen-sphere-errors.md renamed to content/docs/components/generators/protoc-gen-sphere-errors.md

File renamed without changes.

0 commit comments

Comments
 (0)