Add cookbook blog and improve docs (#3002)

As discussed in
https://github.com/woodpecker-ci/woodpecker/discussions/2932#discussioncomment-7842309
Closes #316

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!

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
 ```
 

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.

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 <https://github.com/swaggo/swag/blob/main/README.md#declarative-comments-format>
 
 ### 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
 ```
-
-<!-- markdownlint-disable no-space-in-code -->
-
-**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 <https://github.com/swaggo/swag/pull/1594> == once this is merged and released, the mentioned issue is obsolete.
-
-<!-- markdownlint-enable no-space-in-code -->

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
 

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'),

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",

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)