From 1d6b565de452d24e1db0ca21ba69289809fdc32a Mon Sep 17 00:00:00 2001 From: John Olheiser Date: Fri, 23 Oct 2020 10:59:45 -0500 Subject: [PATCH] Refactor docs (#13275) * First pass Signed-off-by: jolheiser * More changes Signed-off-by: jolheiser * Redirects Signed-off-by: jolheiser --- docs/content/doc/advanced/ci-cd.en-us.md | 37 --------- ...n-us.md => environment-variables.en-us.md} | 10 +-- ...h-cn.md => environment-variables.zh-cn.md} | 4 +- docs/content/doc/advanced/make.en-us.md | 46 ----------- docs/content/doc/advanced/migrations.en-us.md | 81 ------------------- .../doc/advanced/third-party-tools.en-us.md | 43 ---------- docs/content/doc/developers.en-us.md | 13 +++ .../api-usage.en-us.md | 2 +- .../api-usage.zh-cn.md | 2 +- .../hacking-on-gitea.en-us.md | 37 ++++++++- .../doc/developers/integrations.en-us.md | 26 ++++++ .../doc/developers/migrations.en-us.md | 41 ++++++++++ .../oauth2-provider.md | 2 +- docs/content/doc/help/faq.en-us.md | 4 +- .../doc/installation/from-binary.en-us.md | 2 +- .../doc/installation/from-source.en-us.md | 4 +- docs/static/_redirects | 4 + 17 files changed, 132 insertions(+), 226 deletions(-) delete mode 100644 docs/content/doc/advanced/ci-cd.en-us.md rename docs/content/doc/advanced/{specific-variables.en-us.md => environment-variables.en-us.md} (92%) rename docs/content/doc/advanced/{specific-variables.zh-cn.md => environment-variables.zh-cn.md} (96%) delete mode 100644 docs/content/doc/advanced/make.en-us.md delete mode 100644 docs/content/doc/advanced/migrations.en-us.md delete mode 100644 docs/content/doc/advanced/third-party-tools.en-us.md create mode 100644 docs/content/doc/developers.en-us.md rename docs/content/doc/{advanced => developers}/api-usage.en-us.md (99%) rename docs/content/doc/{advanced => developers}/api-usage.zh-cn.md (99%) rename docs/content/doc/{advanced => developers}/hacking-on-gitea.en-us.md (92%) create mode 100644 docs/content/doc/developers/integrations.en-us.md create mode 100644 docs/content/doc/developers/migrations.en-us.md rename docs/content/doc/{advanced => developers}/oauth2-provider.md (99%) diff --git a/docs/content/doc/advanced/ci-cd.en-us.md b/docs/content/doc/advanced/ci-cd.en-us.md deleted file mode 100644 index 7b69d851b..000000000 --- a/docs/content/doc/advanced/ci-cd.en-us.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -date: "2019-08-27:00:00+02:00" -title: "CI/CD Usage" -slug: "ci-cd" -weight: 40 -toc: true -draft: false -menu: - sidebar: - parent: "advanced" - name: "CI/CD Usage" - weight: 40 - identifier: "ci-cd" ---- - -# Gitea and CI/CD -**NOTE:** These tools are not endorsed by Gitea. They are listed here for convenience only. - -## Hey! This page may be out of date or even removed in the future! :scream: -Instead, check out [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md#user-content-devops)! - -## Listing - -CI/CD solutions that have integration with Gitea. Following list is not complete, -the purpose is to give a starting point to integrate a CI/CD process with your Gitea instance. - - - [Drone](https://drone.io) with [Gitea documentation](https://docs.drone.io/installation/providers/gitea/) - - [Jenkins](https://jenkins.io/) with [Gitea plugin](https://plugins.jenkins.io/gitea) - - [Agola](https://agola.io) - - [Buildkite](https://buildkite.com) with [Gitea connector](https://github.com/techknowlogick/gitea-buildkite-connector) - - [AppVeyor](https://www.appveyor.com) with [built-in Gitea support](https://www.appveyor.com/blog/2019/09/05/gitea-receives-first-class-support-in-appveyor/) - - [Buildbot](https://www.buildbot.net/) with [Gitea plugin](https://github.com/lab132/buildbot-gitea) - - -Others CI/CD solutions that can partially be integrated with Gitea: - - - [Concourse](https://www.concourse-ci.org), see more information at [Concourse community forum](https://discuss.concourse-ci.org/t/concourse-ci-and-gitea-oauth/1475) diff --git a/docs/content/doc/advanced/specific-variables.en-us.md b/docs/content/doc/advanced/environment-variables.en-us.md similarity index 92% rename from docs/content/doc/advanced/specific-variables.en-us.md rename to docs/content/doc/advanced/environment-variables.en-us.md index d9c6d3c3e..bfc5fedcf 100644 --- a/docs/content/doc/advanced/specific-variables.en-us.md +++ b/docs/content/doc/advanced/environment-variables.en-us.md @@ -1,19 +1,19 @@ --- date: "2017-04-08T11:34:00+02:00" -title: "Specific variables" -slug: "specific-variables" +title: "Environment variables" +slug: "environment-variables" weight: 20 toc: false draft: false menu: sidebar: parent: "advanced" - name: "Specific variables" + name: "Environment variables" weight: 20 - identifier: "specific-variables" + identifier: "environment-variables" --- -# Specific variables +# Environment variables This is an inventory of Gitea environment variables. They change Gitea behaviour. diff --git a/docs/content/doc/advanced/specific-variables.zh-cn.md b/docs/content/doc/advanced/environment-variables.zh-cn.md similarity index 96% rename from docs/content/doc/advanced/specific-variables.zh-cn.md rename to docs/content/doc/advanced/environment-variables.zh-cn.md index 042e81896..4b936a53f 100644 --- a/docs/content/doc/advanced/specific-variables.zh-cn.md +++ b/docs/content/doc/advanced/environment-variables.zh-cn.md @@ -1,7 +1,7 @@ --- date: "2017-04-08T11:34:00+02:00" title: "环境变量清单" -slug: "specific-variables" +slug: "environment-variables" weight: 20 toc: false draft: false @@ -10,7 +10,7 @@ menu: parent: "advanced" name: "环境变量清单" weight: 20 - identifier: "specific-variables" + identifier: "environment-variables" --- # 环境变量清单 diff --git a/docs/content/doc/advanced/make.en-us.md b/docs/content/doc/advanced/make.en-us.md deleted file mode 100644 index f90367de5..000000000 --- a/docs/content/doc/advanced/make.en-us.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -date: "2017-01-14T11:00:00-02:00" -title: "Make" -slug: "make" -weight: 10 -toc: true -draft: false -menu: - sidebar: - parent: "advanced" - name: "Make" - weight: 30 - identifier: "make" ---- - -# Make - -Gitea makes heavy use of Make to automate tasks and improve development. This -guide covers how to install Make. - -### On Linux - -Install with the package manager. - -On Ubuntu/Debian: - -```bash -sudo apt-get install make -``` - -On Fedora/RHEL/CentOS: - -```bash -sudo yum install make -``` - -### On Windows - -One of these three distributions of Make will run on Windows: - -- [Single binary build](http://www.equation.com/servlet/equation.cmd?fa=make). Copy somewhere and add to `PATH`. - - [32-bits version](ftp://ftp.equation.com/make/32/make.exe) - - [64-bits version](ftp://ftp.equation.com/make/64/make.exe) -- [MinGW](http://www.mingw.org/) includes a build. - - The binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to `PATH`. -- [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make` diff --git a/docs/content/doc/advanced/migrations.en-us.md b/docs/content/doc/advanced/migrations.en-us.md deleted file mode 100644 index 746c68f42..000000000 --- a/docs/content/doc/advanced/migrations.en-us.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -date: "2019-04-15T17:29:00+08:00" -title: "Advanced: Migrations Interfaces" -slug: "migrations-interfaces" -weight: 30 -toc: true -draft: false -menu: - sidebar: - parent: "advanced" - name: "Migrations Interfaces" - weight: 55 - identifier: "migrations-interfaces" ---- - -# Migration Features - -The new migration features were introduced in Gitea 1.9.0. It defines two interfaces to support migrating -repositories data from other git host platforms to gitea or, in the future migrating gitea data to other -git host platforms. Currently, migrations from Github, Gitlab and Gitea to Gitea is implemented. - -First of all, Gitea defines some standard objects in packages `modules/migrations/base`. They are - `Repository`, `Milestone`, `Release`, `ReleaseAsset`, `Label`, `Issue`, `Comment`, `PullRequest`, `Reaction`, `Review`, `ReviewComment`. - -## Downloader Interfaces - -To migrate from a new git host platform, there are two steps to be updated. - -- You should implement a `Downloader` which will get all kinds of repository informations. -- You should implement a `DownloaderFactory` which is used to detect if the URL matches and -create a Downloader. -- You'll need to register the `DownloaderFactory` via `RegisterDownloaderFactory` on init. - -```Go -type Downloader interface { - GetAsset(relTag string, relID, id int64) (io.ReadCloser, error) - SetContext(context.Context) - GetRepoInfo() (*Repository, error) - GetTopics() ([]string, error) - GetMilestones() ([]*Milestone, error) - GetReleases() ([]*Release, error) - GetLabels() ([]*Label, error) - GetIssues(page, perPage int) ([]*Issue, bool, error) - GetComments(issueNumber int64) ([]*Comment, error) - GetPullRequests(page, perPage int) ([]*PullRequest, bool, error) - GetReviews(pullRequestNumber int64) ([]*Review, error) -} -``` - -```Go -type DownloaderFactory interface { - New(ctx context.Context, opts MigrateOptions) (Downloader, error) - GitServiceType() structs.GitServiceType -} -``` - -## Uploader Interface - -Currently, only a `GiteaLocalUploader` is implemented, so we only save downloaded -data via this `Uploader` on the local Gitea instance. Other uploaders are not supported -and will be implemented in future. - -```Go -// Uploader uploads all the informations -type Uploader interface { - MaxBatchInsertSize(tp string) int - CreateRepo(repo *Repository, opts MigrateOptions) error - CreateTopics(topic ...string) error - CreateMilestones(milestones ...*Milestone) error - CreateReleases(downloader Downloader, releases ...*Release) error - SyncTags() error - CreateLabels(labels ...*Label) error - CreateIssues(issues ...*Issue) error - CreateComments(comments ...*Comment) error - CreatePullRequests(prs ...*PullRequest) error - CreateReviews(reviews ...*Review) error - Rollback() error - Close() -} - -``` diff --git a/docs/content/doc/advanced/third-party-tools.en-us.md b/docs/content/doc/advanced/third-party-tools.en-us.md deleted file mode 100644 index 9d7e7d6d6..000000000 --- a/docs/content/doc/advanced/third-party-tools.en-us.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -date: "2018-05-22T11:00:00+00:00" -title: "Advanced: Third Party Tools" -slug: "third-party-tools" -weight: 50 -toc: true -draft: false -menu: - sidebar: - parent: "advanced" - name: "Third Party Tools" - weight: 50 - identifier: "third-party-tools" ---- - -# List of third-party tools -**NOTE:** These tools are not endorsed by Gitea. They are listed here for convenience only. - -## Hey! This page may be out of date or even removed in the future! :scream: -Instead, check out [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md)! - -### Continuous Integration - -Check our [CI/CD page]({{< relref "doc/advanced/ci-cd.en-us.md" >}}) - -### Internationalization -- [Weblate](https://docs.weblate.org/en/latest/admin/continuous.html#gitea-setup) - -### Migrating -- [Installation script for Gitea](https://git.coolaj86.com/coolaj86/gitea-installer.sh) -- [GitHub Migrator](https://gitea.com/gitea/migrator) - - -### Mobile -- [GitNex for Android](https://codeberg.org/gitnex/GitNex) -- [GitTouch for Android and iOS](https://github.com/git-touch/git-touch) - -### Editor Extensions -- [Gitea Extension for Visual Studio](https://github.com/maikebing/Gitea.VisualStudio) - - Download from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=MysticBoy.GiteaExtensionforVisualStudio) - -### Project Management -- [YouTrack by JetBrains](https://blog.jetbrains.com/youtrack/2019/12/whats-new-in-youtrack-2019-3/) diff --git a/docs/content/doc/developers.en-us.md b/docs/content/doc/developers.en-us.md new file mode 100644 index 000000000..c24a23dfa --- /dev/null +++ b/docs/content/doc/developers.en-us.md @@ -0,0 +1,13 @@ +--- +date: "2016-12-01T16:00:00+02:00" +title: "Developers" +slug: "developers" +weight: 40 +toc: false +draft: false +menu: + sidebar: + name: "Developers" + weight: 50 + identifier: "developers" +--- diff --git a/docs/content/doc/advanced/api-usage.en-us.md b/docs/content/doc/developers/api-usage.en-us.md similarity index 99% rename from docs/content/doc/advanced/api-usage.en-us.md rename to docs/content/doc/developers/api-usage.en-us.md index 81ebc42ee..5e979d1e9 100644 --- a/docs/content/doc/advanced/api-usage.en-us.md +++ b/docs/content/doc/developers/api-usage.en-us.md @@ -7,7 +7,7 @@ toc: true draft: false menu: sidebar: - parent: "advanced" + parent: "developers" name: "API Usage" weight: 40 identifier: "api-usage" diff --git a/docs/content/doc/advanced/api-usage.zh-cn.md b/docs/content/doc/developers/api-usage.zh-cn.md similarity index 99% rename from docs/content/doc/advanced/api-usage.zh-cn.md rename to docs/content/doc/developers/api-usage.zh-cn.md index 0f11e040b..cfea23176 100644 --- a/docs/content/doc/advanced/api-usage.zh-cn.md +++ b/docs/content/doc/developers/api-usage.zh-cn.md @@ -7,7 +7,7 @@ toc: true draft: false menu: sidebar: - parent: "advanced" + parent: "developers" name: "API 使用指南" weight: 40 identifier: "api-usage" diff --git a/docs/content/doc/advanced/hacking-on-gitea.en-us.md b/docs/content/doc/developers/hacking-on-gitea.en-us.md similarity index 92% rename from docs/content/doc/advanced/hacking-on-gitea.en-us.md rename to docs/content/doc/developers/hacking-on-gitea.en-us.md index 1d2702a5e..b80ce889a 100644 --- a/docs/content/doc/advanced/hacking-on-gitea.en-us.md +++ b/docs/content/doc/developers/hacking-on-gitea.en-us.md @@ -7,7 +7,7 @@ toc: false draft: false menu: sidebar: - parent: "advanced" + parent: "developers" name: "Hacking on Gitea" weight: 10 identifier: "hacking-on-gitea" @@ -24,9 +24,6 @@ Next, [install Node.js with npm](https://nodejs.org/en/download/) which is required to build the JavaScript and CSS files. The minimum supported Node.js version is {{< min-node-version >}} and the latest LTS version is recommended. -You will also need make. -(See here how to get Make) - **Note**: When executing make tasks that require external tools, like `make misspell-check`, Gitea will automatically download and build these as necessary. To be able to use these you must have the `"$GOPATH"/bin` directory @@ -40,6 +37,38 @@ the results of `gofmt` can differ by the version of `go`. It is therefore recommended to install the version of Go that our continuous integration is running. As of last update, it should be Go version {{< go-version >}}. +## Installing Make + +Gitea makes heavy use of Make to automate tasks and improve development. This +guide covers how to install Make. + +#### On Linux + +Install with the package manager. + +On Ubuntu/Debian: + +```bash +sudo apt-get install make +``` + +On Fedora/RHEL/CentOS: + +```bash +sudo yum install make +``` + +#### On Windows + +One of these three distributions of Make will run on Windows: + +- [Single binary build](http://www.equation.com/servlet/equation.cmd?fa=make). Copy somewhere and add to `PATH`. + - [32-bits version](ftp://ftp.equation.com/make/32/make.exe) + - [64-bits version](ftp://ftp.equation.com/make/64/make.exe) +- [MinGW](http://www.mingw.org/) includes a build. + - The binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to `PATH`. +- [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make` + ## Downloading and cloning the Gitea source code The recommended method of obtaining the source code is by using `git clone`. diff --git a/docs/content/doc/developers/integrations.en-us.md b/docs/content/doc/developers/integrations.en-us.md new file mode 100644 index 000000000..bc8c62637 --- /dev/null +++ b/docs/content/doc/developers/integrations.en-us.md @@ -0,0 +1,26 @@ +--- +date: "2019-04-15T17:29:00+08:00" +title: "Integrations" +slug: "integrations" +weight: 40 +toc: true +draft: false +menu: + sidebar: + parent: "developers" + name: "Integrations" + weight: 65 + identifier: "integrations" +--- + +# Integrations + +Gitea has a wonderful community of third-party integrations, as well as first-class support in various other +projects. + +We are curating a list over at [awesome-gitea](https://gitea.com/gitea/awesome-gitea) to track these! + +If you are looking for [CI/CD](https://gitea.com/gitea/awesome-gitea#devops), +an [SDK](https://gitea.com/gitea/awesome-gitea#sdk), +or even some extra [themes](https://gitea.com/gitea/awesome-gitea#themes), +you can find them listed in the [awesome-gitea](https://gitea.com/gitea/awesome-gitea) repository! diff --git a/docs/content/doc/developers/migrations.en-us.md b/docs/content/doc/developers/migrations.en-us.md new file mode 100644 index 000000000..7af013896 --- /dev/null +++ b/docs/content/doc/developers/migrations.en-us.md @@ -0,0 +1,41 @@ +--- +date: "2019-04-15T17:29:00+08:00" +title: "Migrations Interfaces" +slug: "migrations-interfaces" +weight: 30 +toc: true +draft: false +menu: + sidebar: + parent: "developers" + name: "Migrations Interfaces" + weight: 55 + identifier: "migrations-interfaces" +--- + +# Migration Features + +Complete migrations were introduced in Gitea 1.9.0. It defines two interfaces to support migrating +repository data from other git host platforms to Gitea or, in the future, migrating Gitea data to other +git host platforms. +Currently, migrations from Github, Gitlab, and other Gitea instances are implemented. + +First of all, Gitea defines some standard objects in packages [modules/migrations/base](https://github.com/go-gitea/gitea/tree/master/modules/migrations/base). +They are `Repository`, `Milestone`, `Release`, `ReleaseAsset`, `Label`, `Issue`, `Comment`, `PullRequest`, `Reaction`, `Review`, `ReviewComment`. + +## Downloader Interfaces + +To migrate from a new git host platform, there are two steps to be updated. + +- You should implement a `Downloader` which will be used to get repository information. +- You should implement a `DownloaderFactory` which will be used to detect if the URL matches and create the above `Downloader`. + - You'll need to register the `DownloaderFactory` via `RegisterDownloaderFactory` on `init()`. + +You can find these interfaces in [downloader.go](https://github.com/go-gitea/gitea/blob/master/modules/migrations/base/downloader.go). + +## Uploader Interface + +Currently, only a `GiteaLocalUploader` is implemented, so we only save downloaded +data via this `Uploader` to the local Gitea instance. Other uploaders are not supported at this time. + +You can find these interfaces in [uploader.go](https://github.com/go-gitea/gitea/blob/master/modules/migrations/base/uploader.go). diff --git a/docs/content/doc/advanced/oauth2-provider.md b/docs/content/doc/developers/oauth2-provider.md similarity index 99% rename from docs/content/doc/advanced/oauth2-provider.md rename to docs/content/doc/developers/oauth2-provider.md index c924d1ce0..87d636d37 100644 --- a/docs/content/doc/advanced/oauth2-provider.md +++ b/docs/content/doc/developers/oauth2-provider.md @@ -7,7 +7,7 @@ toc: true draft: false menu: sidebar: - parent: "advanced" + parent: "developers" name: "OAuth2 Provider" weight: 41 identifier: "oauth2-provider" diff --git a/docs/content/doc/help/faq.en-us.md b/docs/content/doc/help/faq.en-us.md index 7a7044f61..34e6bca3a 100644 --- a/docs/content/doc/help/faq.en-us.md +++ b/docs/content/doc/help/faq.en-us.md @@ -129,7 +129,7 @@ A "login prohibited" user is a user that is not allowed to log in to Gitea anymo ## What is Swagger? [Swagger](https://swagger.io/) is what Gitea uses for its API. All Gitea instances have the built-in API, though it can be disabled by setting `ENABLE_SWAGGER` to `false` in the `api` section of your `app.ini` -For more information, refer to Gitea's [API docs]({{< relref "doc/advanced/api-usage.en-us.md" >}}) +For more information, refer to Gitea's [API docs]({{< relref "doc/developers/api-usage.en-us.md" >}}) [Swagger Example](https://try.gitea.io/api/swagger) @@ -140,7 +140,7 @@ There are multiple things you can combine to prevent spammers. 1. By only whitelisting certain domains with OpenID (see below) 2. Setting `ENABLE_CAPTCHA` to `true` in your `app.ini` and properly configuring `RECAPTCHA_SECRET` and `RECAPTCHA_SITEKEY` -3. Settings `DISABLE_REGISTRATION` to `true` and creating new users via the [CLI]({{< relref "doc/usage/command-line.en-us.md" >}}), [API]({{< relref "doc/advanced/api-usage.en-us.md" >}}), or Gitea's Admin UI +3. Settings `DISABLE_REGISTRATION` to `true` and creating new users via the [CLI]({{< relref "doc/usage/command-line.en-us.md" >}}), [API]({{< relref "doc/developers/api-usage.en-us.md" >}}), or Gitea's Admin UI ### Only allow certain email domains You can configure `EMAIL_DOMAIN_WHITELIST` in your app.ini under `[service]` diff --git a/docs/content/doc/installation/from-binary.en-us.md b/docs/content/doc/installation/from-binary.en-us.md index 0bd24f468..794b165f6 100644 --- a/docs/content/doc/installation/from-binary.en-us.md +++ b/docs/content/doc/installation/from-binary.en-us.md @@ -35,7 +35,7 @@ gpg --verify gitea-{{< version >}}-linux-amd64.asc gitea-{{< version >}}-linux-a ## Recommended server configuration -**NOTE:** Many of the following directories can be configured using [Environment Variables]({{< relref "doc/advanced/specific-variables.en-us.md" >}}) as well! +**NOTE:** Many of the following directories can be configured using [Environment Variables]({{< relref "doc/advanced/environment-variables.en-us.md" >}}) as well! Of note, configuring `GITEA_WORK_DIR` will tell Gitea where to base its working directory, as well as ease installation. ### Prepare environment diff --git a/docs/content/doc/installation/from-source.en-us.md b/docs/content/doc/installation/from-source.en-us.md index 9bf5c55f0..19093447f 100644 --- a/docs/content/doc/installation/from-source.en-us.md +++ b/docs/content/doc/installation/from-source.en-us.md @@ -33,7 +33,7 @@ executable path, you will have to manage this yourself. **Note 2**: Go version {{< min-go-version >}} or higher is required. However, it is recommended to obtain the same version as our continuous integration, see the advice given in -Hacking on +Hacking on Gitea ## Download @@ -83,7 +83,7 @@ To build from source, the following programs must be present on the system: - `go` {{< min-go-version >}} or higher, see [here](https://golang.org/dl/) - `node` {{< min-node-version >}} or higher with `npm`, see [here](https://nodejs.org/en/download/) -- `make`, see here +- `make`, see here Various [make tasks](https://github.com/go-gitea/gitea/blob/master/Makefile) are provided to keep the build process as simple as possible. diff --git a/docs/static/_redirects b/docs/static/_redirects index 0eb23153a..2114ae933 100644 --- a/docs/static/_redirects +++ b/docs/static/_redirects @@ -6,3 +6,7 @@ https://gitea-docs.netlify.com/* https://docs.gitea.io/:splat 302! / /zh-cn/ 302! Language=zh-cn / /zh-tw/ 302! Language=zh-tw / /en-us/ 302! + +/en-us/ci-cd/ /en-us/integrations/ 302! +/en-us/third-party-tools/ /en-us/integrations/ 302! +/en-us/make/ /en-us/hacking-on-gitea/ 302!