diff --git a/docs/cookbook/2023-12-23-hello-cookbook/index.md b/docs/cookbook/2023-12-23-hello-cookbook/index.md new file mode 100644 index 000000000..d3055dfba --- /dev/null +++ b/docs/cookbook/2023-12-23-hello-cookbook/index.md @@ -0,0 +1,13 @@ +--- +title: Welcome to Woodpecker's cookbook blog +description: Here, we'll publish various guides and tutorials. +slug: hello-cookbook +authors: + - name: qwerty287 + title: Maintainer of Woodpecker + url: https://github.com/qwerty287 + image_url: https://github.com/qwerty287.png +hide_table_of_contents: false +--- + +Welcome to this cookbook blog. Here, we and any other interested user can publish guides and tutorials. If you got something in mind, just add your guide! diff --git a/docs/docs/10-intro.md b/docs/docs/10-intro.md index 78a838add..5a36deb65 100644 --- a/docs/docs/10-intro.md +++ b/docs/docs/10-intro.md @@ -69,8 +69,7 @@ COPY deploy /usr/local/deploy ENTRYPOINT ["/usr/local/deploy"] ``` -```bash -# deploy +```bash title="deploy" kubectl apply -f $PLUGIN_TEMPLATE ``` diff --git a/docs/docs/92-development/06-guides.md b/docs/docs/92-development/06-guides.md index d78e4f322..e8db28a53 100644 --- a/docs/docs/92-development/06-guides.md +++ b/docs/docs/92-development/06-guides.md @@ -7,22 +7,7 @@ You can find its documentation at [gobook.io/read/gitea.com/xorm](https://gobook ## Add a new migration -Woodpecker uses migrations to change the database schema if a database model has been changed. If for example a developer removes a property `Counter` from the model `Repo` in `server/model/` they would need to add a new migration task like the following example to a file like `server/store/datastore/migration/004_repos_drop_repo_counter.go`: - -```go -package migration - -import ( - "xorm.io/xorm" -) - -var alterTableReposDropCounter = task{ - name: "alter-table-drop-counter", - fn: func(sess *xorm.Session) error { - return dropTableColumns(sess, "repos", "repo_counter") - }, -} -``` +Woodpecker uses migrations to change the database schema if a database model has been changed. Add the new migration task into `server/store/datastore/migration/`. :::info Adding new properties to models will be handled automatically by the underlying [ORM](#orm) based on the [struct field tags](https://stackoverflow.com/questions/10858787/what-are-the-uses-for-tags-in-go) of the model. If you add a completely new model, you have to add it to the `allBeans` variable at `server/store/datastore/migration/migration.go` to get a new table created. diff --git a/docs/docs/92-development/08-swagger.md b/docs/docs/92-development/08-swagger.md index 69cc97aab..92505a8fc 100644 --- a/docs/docs/92-development/08-swagger.md +++ b/docs/docs/92-development/08-swagger.md @@ -15,8 +15,7 @@ You don't require any extra tools on your machine, all Swagger tooling is automa Here's a typical example of how annotations for Swagger documentation look like... -```text ---- server/api/user.go --- +```go title="server/api/user.go" // @Summary Get a user // @Description Returns a user with the specified login name. Requires admin rights. // @Router /users/{login} [get] @@ -30,8 +29,7 @@ Here's a typical example of how annotations for Swagger documentation look like. // @Param perPage query int false "for response pagination, max items per page" default(50) ``` -```text ---- server/model/user.go --- +```go title="server/model/user.go" type User struct { ID int64 `json:"id" xorm:"pk autoincr 'user_id'"` // ... @@ -41,41 +39,25 @@ type User struct { These guidelines aim to have consistent wording in the swagger doc: - first word after `@Summary` and `@Summary` are always uppercase -- `@Summary` has no . (dot) at the end of the line +- `@Summary` has no `.` (dot) at the end of the line - model structs shall use custom short names, to ease life for API consumers, using `@name` - `@Success` object or array declarations shall be short, this means the actual `model.User` struct must have a `@name` annotation, so that the model can be renderend in Swagger - when pagination is used, `@Parame page` and `@Parame perPage` must be added manually - `@Param Authorization` is almost always present, there are just a few un-protected endpoints -There are many examples in the server/api package, which you can use a blueprint. +There are many examples in the `server/api` package, which you can use a blueprint. More enhanced information you can find here ### Manual code generation -#### generate the server's Go code containing the Swagger - -```bash +```bash title="generate the server's Go code containing the Swagger" make generate-swagger ``` -##### update the Markdown in the ./docs folder - -```bash +```bash title="update the Markdown in the ./docs folder" make docs ``` -##### auto-format swagger related godoc - -```bash +```bash title="auto-format swagger related godoc" go run github.com/swaggo/swag/cmd/swag@latest fmt -g server/api/z.go ``` - - - -**WARNING, known issue**: using swag v1.18.12 , there's a bug when running the `fmt` command, -which makes the swagger generator failing, because it can't find the models/structs/types anymore. -To fix it, please replace `// @name\tModelName` with `// @name ModelName`, -which means, replace the tab (`\t`) with a space (` `). -See == once this is merged and released, the mentioned issue is obsolete. - - diff --git a/docs/docs/92-development/09-security.md b/docs/docs/92-development/09-security.md index 2491fe0cc..24517c843 100644 --- a/docs/docs/92-development/09-security.md +++ b/docs/docs/92-development/09-security.md @@ -1,7 +1,7 @@ # Security We take security seriously. -If you discover a security issue, please bring it to their attention right away! +If you discover a security issue, please bring it to our attention right away! ## Reporting a Vulnerability diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 0a158854f..3e647cfe8 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -57,6 +57,7 @@ const config: Config = { label: 'API', }, { to: 'blog', label: 'Blog', position: 'left' }, + { to: 'cookbook', label: 'Cookbook', position: 'left' }, { type: 'docsVersionDropdown', position: 'right', @@ -192,6 +193,21 @@ const config: Config = { }; }, }), + [ + '@docusaurus/plugin-content-blog', + { + id: 'cookbook-blog', + /** + * URL route for the blog section of your site. + * *DO NOT* include a trailing slash. + */ + routeBasePath: 'cookbook', + /** + * Path to data on filesystem relative to site dir. + */ + path: './cookbook', + }, + ], ], themes: [ path.resolve(__dirname, 'plugins', 'woodpecker-plugins', 'dist'), diff --git a/docs/package.json b/docs/package.json index f31977bc2..5fa424956 100644 --- a/docs/package.json +++ b/docs/package.json @@ -15,6 +15,7 @@ }, "dependencies": { "@docusaurus/core": "^3.0.0", + "@docusaurus/plugin-content-blog": "^3.0.1", "@docusaurus/preset-classic": "^3.0.0", "@easyops-cn/docusaurus-search-local": "^0.40.0", "@mdx-js/react": "^3.0.0", diff --git a/docs/pnpm-lock.yaml b/docs/pnpm-lock.yaml index e57b758bd..4acce3926 100644 --- a/docs/pnpm-lock.yaml +++ b/docs/pnpm-lock.yaml @@ -15,6 +15,9 @@ importers: '@docusaurus/core': specifier: ^3.0.0 version: 3.0.1(@docusaurus/types@3.0.1)(debug@4.3.4)(react-dom@18.2.0)(react@18.2.0)(typescript@5.3.2) + '@docusaurus/plugin-content-blog': + specifier: ^3.0.1 + version: 3.0.1(react-dom@18.2.0)(react@18.2.0)(typescript@5.3.2) '@docusaurus/preset-classic': specifier: ^3.0.0 version: 3.0.1(@algolia/client-search@4.20.0)(@types/react@18.2.42)(react-dom@18.2.0)(react@18.2.0)(search-insights@2.11.0)(typescript@5.3.2)