From 8a138d4aa51043d3c2289adc32150538952f173f Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Mon, 18 Mar 2024 17:18:05 +0100 Subject: [PATCH] doc: push released documentation sets Signed-off-by: Frederic BIDON --- .github/workflows/release-doc.yaml | 118 +++++++++++++++++++++++++++++ .github/workflows/update-doc.yaml | 13 ++-- docs/_index.md | 31 +++++--- hack/doc-site/hugo/hugo.yaml | 3 +- 4 files changed, 147 insertions(+), 18 deletions(-) create mode 100644 .github/workflows/release-doc.yaml diff --git a/.github/workflows/release-doc.yaml b/.github/workflows/release-doc.yaml new file mode 100644 index 000000000..4102bb89d --- /dev/null +++ b/.github/workflows/release-doc.yaml @@ -0,0 +1,118 @@ +name: "Release documentation set" + +on: + push: + tags: + - v* + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +defaults: + run: + shell: bash + +jobs: + build-doc: + runs-on: ubuntu-latest + steps: + - + name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: '1' + #fetch-tags: 'true' + submodules: recursive + sparse-checkout: | + hack/ + docs/ + - name: Get all tags + run: git fetch --prune --unshallow --tags + - + name: Initialize themes + run: | + (cd hack/doc-site/hugo/ && git clone https://github.com/alex-shpak/hugo-book themes/hugo-book) + + - + name: Checkout github pages main site + uses: actions/checkout@v4 + with: + repository: fredbi/go-swagger.github.io + #repository: go-swagger/go-swagger.github.io + path: hack/doc-site/github-pages + sparse-checkout: | + index.html + fetch-depth: '1' + + - + name: Prepare config + run: | + # Builds a commit-dependant extra config to inject parameterization. + # HUGO doesn't support config from the command line. + # + # Set go-swagger specific parameters that are used in some parameterized documents + # This is used to keep up-to-date installation instructions. + cd hack/doc-site/hugo + + #SITE="https://goswagger.io" + SITE="https://fredbi.github.io" + LATEST_RELEASE=$(git describe --tags --abbrev=0) + VERSION_MESSAGE="Documentation set for release ${LATEST_RELEASE}." + ROOT=$(git rev-parse --show-toplevel) + REQUIRED_GO_VERSION=$(grep "^go\s" "${ROOT}"/go.mod|cut -d" " -f2) + printf \ + "params:\n goswagger:\n goVersion: '%s'\n latestRelease: '%s'\n versionMessage: '%s'\n" \ + "${REQUIRED_GO_VERSION}" "${LATEST_RELEASE}" "${VERSION_MESSAGE}" > goswagger.yaml + + # Tweak HUGO configuration to produce released documentation site at {url}/vx.y.z. + sed 's/^baseURL:[[:space:]]*\(.\+\)$/baseURL: '$(echo "${SITE}/${LATEST_RELEASE}"|sed 's/\//\\\//g')'/' hugo.yaml | \ + sed 's/^[[:space:]]\+BookEditPath:\(.\+\)$/ #BookEditPath:\1/' > release.yaml + + echo "::debug::Configuration file for release" $(cat release.yaml) + + - + name: Build release site with Hugo + uses: crazy-max/ghaction-hugo@v3 + with: + version: v0.123.8 # <- pin the HUGO version, at they often break things + extended: true + args: > + --config release.yaml,goswagger.yaml + --buildDrafts + --cleanDestinationDir + --minify + --printPathWarnings + --ignoreCache + --noBuildLock + --logLevel info + --source ${{ github.workspace }}/hack/doc-site/hugo" + + - + name: Copy generated site + run: | + ROOT=$(git rev-parse --show-toplevel) + cd hack/doc-site/github-pages + + LATEST_RELEASE=$(git describe --tags --abbrev=0) + mkdir "${LATEST_RELEASE)" + (cd "${ROOT}"/hack/doc-site/hugo/public ; tar cf -)| (cd "${LATEST_RELEASE}" ; tar xf -) + + - + name: Create PR for goswagger.github.io + run: | + cd $(git rev-parse --show-toplevel) + LATEST_RELEASE=$(git describe --tags --abbrev=0) + BRANCH="doc/${LATEST_RELEASE}" + cd hack/doc-site/github-pages + + git checkout -b "${BRANCH}" + git add "${LATEST_RELEASE}" + git commit -s -m "doc: release documentation set for release ${LATEST_RELEASE}" + git push --set-upstream origin "${BRANCH}" + gh pr create -R fredbi/go-swagger.github.io --fill --base master --label release --label "${LATEST_RELEASE}" diff --git a/.github/workflows/update-doc.yaml b/.github/workflows/update-doc.yaml index bd085e988..7475faa11 100644 --- a/.github/workflows/update-doc.yaml +++ b/.github/workflows/update-doc.yaml @@ -2,8 +2,6 @@ name: "Update documentation" on: push: - tags: - - v* branches: [ "master" ] paths: - docs/** @@ -59,15 +57,20 @@ jobs: # Set go-swagger specific parameters that are used in some parameterized documents # This is used to keep up-to-date installation instructions. cd hack/doc-site/hugo + + URL="https://goswagger.io" LATEST_RELEASE=$(git describe --tags --abbrev=0) + VERSION_MESSAGE="Documentation set for latest master." ROOT=$(git rev-parse --show-toplevel) REQUIRED_GO_VERSION=$(grep "^go\s" "${ROOT}"/go.mod|cut -d" " -f2) printf \ - "params:\n goswagger:\n goVersion: '%s'\n latestRelease: '%s'\n" \ - "${REQUIRED_GO_VERSION}" "${LATEST_RELEASE}" > goswagger.yaml + "params:\n goswagger:\n goVersion: '%s'\n latestRelease: '%s'\n versionMessage: '%s'\n" \ + "${URL}/${LATEST_RELEASE}" "${REQUIRED_GO_VERSION}" "${LATEST_RELEASE}" "${VERSION_MESSAGE}" > goswagger.yaml + + sed '' hugo.yaml - - name: Build site with Hugo + name: Build site with Hugo for released documentation set uses: crazy-max/ghaction-hugo@v3 with: version: v0.123.8 # <- pin the HUGO version, at they often break things diff --git a/docs/_index.md b/docs/_index.md index 859463381..0ba8c7b20 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -5,6 +5,10 @@ draft: true weight: 1 --- {{}} + +{{< hint "info" >}} +{{< param goswagger.versionMessage >}} +{{< /hint >}} # Swagger 2.0 [![Build Status](https://circleci.com/gh/go-swagger/go-swagger.svg?style=shield)](https://circleci.com/gh/go-swagger/go-swagger) [![Build status](https://ci.appveyor.com/api/projects/status/x377t5o9ennm847o/branch/master?svg=true)](https://ci.appveyor.com/project/casualjim/go-swagger/branch/master) [![codecov](https://codecov.io/gh/go-swagger/go-swagger/branch/master/graph/badge.svg)](https://codecov.io/gh/go-swagger/go-swagger) [![GitHub version](https://badge.fury.io/gh/go-swagger%2Fgo-swagger.svg)](https://badge.fury.io/gh/go-swagger%2Fgo-swagger) [![Slack Status](https://slackin.goswagger.io/badge.svg)](https://slackin.goswagger.io) @@ -51,12 +55,15 @@ The go-openapi community actively continues bringing fixes and enhancements to t There is still much room for improvement: contributors and PR's are welcome. You may also get in touch with maintainers on [our slack channel](https://slackin.goswagger.io). ## Documentation - +Latest master: + +Documentation sets for released versions: +* Latest release: +* Other releases: ## FAQ -Q&A contributed by the community: - +[Q&A contributed by the community](faq) ## How is this different from go generator in swagger-codegen? **tl;dr** The main difference at this moment is that this one actually works... @@ -77,7 +84,7 @@ Further, the go server generated by swagger-codegen is mostly a stub. ## What's inside? -Here is an outline of available features (see the full list [here](https://goswagger.io/features.html)): +Here is an outline of available features (see the full list [here](features.md)): - An object model that serializes swagger-compliant yaml or json - A tool to work with swagger @@ -97,14 +104,14 @@ Here is an outline of available features (see the full list [here](https://goswa There is more to that... -- A [typed JSON Schema implementation](https://goswagger.io/use/model.html), supporting most Draft 4 features +- A [typed JSON Schema implementation](reference/models), supporting most Draft 4 features - Extended string and numeric formats: [strfmt](https://github.com/go-openapi/strfmt) - Utilities to work with JSON, convert data types and pointers: [swag](https://github.com/go-openapi/swag) - A jsonschema (Draft 4) validator, with full $ref support: [validate](https://github.com/go-openapi/validate) - Custom validation interface ## Installing -`go-swagger` is available as binary or docker releases as well as from source: [more details](https://goswagger.io/install.html). +`go-swagger` is available as binary or docker releases as well as from source: [more details](install). ## Use-cases The main package of the toolkit, go-swagger/go-swagger, provides command line tools to help working with swagger. @@ -113,7 +120,7 @@ The toolkit is highly customizable and allows endless possibilities to work with Beside the go-swagger CLI tool and generator, the [go-openapi packages](https://github.com/go-openapi) provide modular functionality to build custom solutions on top of OpenAPI. -The CLI supports shell autocompletion utilities: see [here](https://goswagger.io/cli_helpers.html). +The CLI supports shell autocompletion utilities: see [here](usage/cli_helpers.md). ### Serve specification UI Most basic use-case: serve a UI for your spec: @@ -123,21 +130,21 @@ swagger serve https://raw.githubusercontent.com/swagger-api/swagger-spec/master/ ``` ### Validate a specification -To [validate](https://goswagger.io/usage/validate.html) a Swagger specification: +To [validate](usage/validate.md) a Swagger specification: ``` swagger validate https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore-expanded.json ``` ### Generate an API server -To generate a [server for a swagger spec](https://goswagger.io/generate/server.html) document: +To generate a [server for a swagger spec](generate/server.md) document: ``` swagger generate server [-f ./swagger.json] -A [application-name [--principal [principal-name]] ``` ### Generate an API client -To generate a [client for a swagger spec](https://goswagger.io/generate/client.html) document: +To generate a [client for a swagger spec](generate/client.md) document: ``` swagger generate client [-f ./swagger.json] -A [application-name [--principal [principal-name]] @@ -148,7 +155,7 @@ To generate a [CLI for a swagger spec](https://github.com/go-swagger/go-swagger/ swagger generate cli [-f ./swagger.json] -A [application-name [--principal [principal-name]] ``` ### Generate a spec from source -To generate a [swagger spec document for a go application](https://goswagger.io/generate/spec.html): +To generate a [swagger spec document for a go application](generate-spec/spec.md): ``` swagger generate spec -o ./swagger.json @@ -163,7 +170,7 @@ swagger generate model --spec={spec} ### Transform specs -There are [several commands](https://goswagger.io/use/transform.html) allowing you to transform your spec. +There are [several commands](reference/transform) allowing you to transform your spec. Resolve and expand $ref's in your spec as inline definitions: ``` diff --git a/hack/doc-site/hugo/hugo.yaml b/hack/doc-site/hugo/hugo.yaml index e49292912..9f022edab 100644 --- a/hack/doc-site/hugo/hugo.yaml +++ b/hack/doc-site/hugo/hugo.yaml @@ -11,7 +11,8 @@ theme: hugo-book enableEmoji: true -baseURL: https://goswagger.io/go-swagger +#baseURL: https://goswagger.io/go-swagger +baseURL: https:///fredbi.github.io/go-swagger module: imports: