From 1ba3ac7c99b1cbafab3b68eabdcba06bbf40ba5b Mon Sep 17 00:00:00 2001 From: HesterG Date: Thu, 8 Jun 2023 03:34:23 +0000 Subject: [PATCH] Add outdated component to outdated documents (#25) - `git log` needs all commit history to compare latest commit of files, so changed `git clone --depth=1` to `git clone`. This will make the step take longer, so might be improved if there is a better way. - `src/theme/MDXContent/index.js` is from [ejecting of the component](https://docusaurus.io/docs/swizzling#ejecting) inside `@docusaurus/theme-classic` plugin, and this one is safe to eject according to docusaurus ![Screen Shot 2023-06-06 at 12.12.28](/attachments/17a3a84b-cec0-4849-8bd6-9e0471d9536f) ![Screen Shot 2023-06-06 at 12.12.15](/attachments/58bba321-3cfb-4a8b-8aeb-84422a06c472) - [Outdated component style reference](https://mui.com/material-ui/react-alert/) - Added [`Translate` component](https://docusaurus.io/docs/next/docusaurus-core#translate) to `Outdated` so it can be localized. [reference](https://docusaurus.io/docs/next/i18n/tutorial#translate-your-react-code) - One way to check for the specific outdated documents: search for `lastest commit timestamp` in [prepare nightly docs and prepare 1.19 docs steps](https://gitea.com/gitea/gitea-docusaurus/actions/runs/74) # After The Chinese documents that are outdated (latest commit is ealier than laster commit of English version): ![Screen Shot 2023-06-06 at 13.04.24](/attachments/e5d16267-d8d8-434e-89b1-138d04ec92a3) ![Screen Shot 2023-06-06 at 13.05.07](/attachments/af8f996a-5318-4f89-841f-b27a4903a27d) ![Screen Shot 2023-06-06 at 13.05.14](/attachments/e6aba31b-46ba-4a32-ad81-81007e0f711e) Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/25 Reviewed-by: Lunny Xiao Co-authored-by: HesterG Co-committed-by: HesterG --- Makefile | 6 ++- check_outdated.sh | 38 +++++++++++++++++++ docusaurus.config.js | 16 +++----- .../current.json | 0 i18n/zh-cn/code.json | 8 ++++ loop_docs-19-zh-cn.sh | 4 +- loop_docs-19.sh | 7 ++-- loop_docs-zh-cn.sh | 4 +- loop_docs.sh | 6 ++- src/components/Outdated.js | 17 +++++++++ src/css/custom.css | 21 ++++++++++ src/theme/MDXContent/index.js | 16 ++++++++ 12 files changed, 122 insertions(+), 21 deletions(-) create mode 100755 check_outdated.sh rename i18n/{en => en-us}/docusaurus-plugin-content-docs/current.json (100%) create mode 100644 i18n/zh-cn/code.json create mode 100644 src/components/Outdated.js create mode 100644 src/theme/MDXContent/index.js diff --git a/Makefile b/Makefile index 4fb67813..e409e784 100644 --- a/Makefile +++ b/Makefile @@ -13,10 +13,11 @@ create_dir: .PHONY: clone_main clone_main: create_dir - git clone --depth=1 --branch=main https://github.com/go-gitea/gitea.git .tmp/upstream-docs-latest + git clone --branch=main https://github.com/go-gitea/gitea.git .tmp/upstream-docs-latest cur_path=`pwd` cd .tmp/upstream-docs-latest/docs && make trans-copy cd $(cur_path) + bash check_outdated.sh latest zh-cn .PHONY: prepare-latest prepare-latest: clone_main @@ -37,10 +38,11 @@ prepare-latest-zh-cn: .PHONY: clone_\#% clone_\#%: create_dir - git clone --depth=1 --branch=release/v1.$* https://github.com/go-gitea/gitea.git .tmp/upstream-docs-$* + git clone --branch=release/v1.$* https://github.com/go-gitea/gitea.git .tmp/upstream-docs-$* cur_path=`pwd` cd .tmp/upstream-docs-$*/docs && make trans-copy cd $(cur_path) + bash check_outdated.sh $* zh-cn .PHONY: prepare\#% prepare\#%: clone_\#% diff --git a/check_outdated.sh b/check_outdated.sh new file mode 100755 index 00000000..6cfcd5c4 --- /dev/null +++ b/check_outdated.sh @@ -0,0 +1,38 @@ +#!/bin/bash + +# The script takes two params: +# version: "latest" or a specific version number +# locale +# This script checks if a specific locale version of document is up to date with English version +# If latest commit timestamp of English version is greater than the specific locale version, +# The specific locale version document will be marked as outdated + +set -xe + +if sed --version 2>/dev/null | grep -q GNU; then + SED_INPLACE="sed -i" +else + SED_INPLACE="sed -i ''" +fi +version="$1" +locale="$2" +cur_path=`pwd` +cd .tmp/upstream-docs-"$version" + +for file in `find ./docs/content/doc -name "*.${locale}.md"`; do + file_en="${file/.${locale}/.en-us}" + if [ ! -f "$file_en" ]; then + continue + fi + latest_commit_time_en=$(git log -1 --format=%ct "$file_en") + latest_commit_time_locale=$(git log -1 --format=%ct "$file") + if [ -z "$latest_commit_time_locale" ]; then + continue + fi + if [[ "$latest_commit_time_en" -gt "$latest_commit_time_locale" ]]; then + echo "file: $file, lastest commit timestamp: $latest_commit_time_en (en ver), $latest_commit_time_locale ($locale ver)" + $SED_INPLACE '1s/---/---\nisOutdated: true/' $file + fi +done + +cd "$cur_path" diff --git a/docusaurus.config.js b/docusaurus.config.js index 2dddd313..1d051dde 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -24,12 +24,11 @@ const config = { favicon: 'img/favicon.png', i18n: { - defaultLocale: 'en', - locales: ['en', 'zh-cn'/*, 'fr-fr', 'zh-tw'*/], // temporarily disable other locales + defaultLocale: 'en-us', + locales: ['en-us', 'zh-cn'/*, 'fr-fr', 'zh-tw'*/], // temporarily disable other locales localeConfigs: { - 'en': { + 'en-us': { label: 'English', - htmlLang: 'en-US', }, 'zh-cn': { label: '中文', @@ -47,15 +46,12 @@ const config = { sidebarPath: require.resolve('./sidebars.js'), routeBasePath: '/', // Serve the docs at the site's root editUrl: ({versionDocsDirPath, docPath, locale, version, permalink}) => { - let fileName = `doc/${docPath.replace('.md', '')}.en-us.md`; - if (locale === 'zh-cn') { - fileName = `doc/${docPath.replace('.md', '')}.zh-cn.md`; - } + let fileName = `doc/${docPath.replace('.md', '')}.${locale}.md`; // intro.md has different name from upstream, need to handle this here if (docPath.includes('intro.md')) { - fileName = locale === 'zh-cn' ? 'page/index.zh-cn.md': 'page/index.en-us.md'; + fileName = `page/index.${locale}.md`; } - return `https://github.com/go-gitea/gitea/tree/main/docs/content/${fileName}`; + return `https://github.com/go-gitea/gitea/tree/${version === 'current' ? 'main': `release/v${version}`}/docs/content/${fileName}`; }, versions: { current: { diff --git a/i18n/en/docusaurus-plugin-content-docs/current.json b/i18n/en-us/docusaurus-plugin-content-docs/current.json similarity index 100% rename from i18n/en/docusaurus-plugin-content-docs/current.json rename to i18n/en-us/docusaurus-plugin-content-docs/current.json diff --git a/i18n/zh-cn/code.json b/i18n/zh-cn/code.json new file mode 100644 index 00000000..627cf77d --- /dev/null +++ b/i18n/zh-cn/code.json @@ -0,0 +1,8 @@ +{ + "outdated.message": { + "message": "当前中文文档翻译不是最新版，访问英文版本查看最新内容，或" + }, + "outdated.help": { + "message": "帮助我们翻译" + } +} diff --git a/loop_docs-19-zh-cn.sh b/loop_docs-19-zh-cn.sh index d4b1c312..2b8ff434 100644 --- a/loop_docs-19-zh-cn.sh +++ b/loop_docs-19-zh-cn.sh @@ -22,7 +22,7 @@ $SED_INPLACE 's/{{< min-go-version >}}/1.19/' i18n/zh-cn/docusaurus-plugin-conte $SED_INPLACE 's/"version":.*/"version":"1.19.0"/' static/19-swagger.json -for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/ -name "*.md"`; do +for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19 -name "*.md"`; do # note only works on linux, forget about it when attempting to run on macos # hide hugo toc $SED_INPLACE 's/{{< toc >}}//' $file @@ -44,7 +44,7 @@ for file in i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/*; do rm $file done -for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/ -name "*.zh-cn.md"`; do +for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19 -name "*.zh-cn.md"`; do mv "${file}" "${file/.zh-cn/}" done diff --git a/loop_docs-19.sh b/loop_docs-19.sh index c93162bf..a7c94cb9 100644 --- a/loop_docs-19.sh +++ b/loop_docs-19.sh @@ -21,7 +21,7 @@ $SED_INPLACE 's/{{< min-go-version >}}/1.19/' versioned_docs/version-1.19/instal $SED_INPLACE 's/"version":.*/"version":"1.19.3"/' static/19-swagger.json -for file in `find ./versioned_docs/version-1.19/ -name "*.md"`; do +for file in `find ./versioned_docs/version-1.19 -name "*.md"`; do # hide hugo toc $SED_INPLACE 's/{{< toc >}}//' $file $SED_INPLACE 's/{{< version >}}/1.19.3/g' $file @@ -44,7 +44,8 @@ for file in versioned_docs/version-1.19/*; do fi rm $file done - -for file in `find ./versioned_docs/version-1.19/ -name "*.en-us.md"`; do +# file names under ./versioned_docs/version-1.19 and i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/ should be the same for docusaurus +# to recognize them as tanslated. +for file in `find ./versioned_docs/version-1.19 -name "*.en-us.md"`; do mv "${file}" "${file/.en-us/}" done diff --git a/loop_docs-zh-cn.sh b/loop_docs-zh-cn.sh index d98e9f53..1707e5c1 100644 --- a/loop_docs-zh-cn.sh +++ b/loop_docs-zh-cn.sh @@ -22,7 +22,7 @@ $SED_INPLACE 's/{{< min-go-version >}}/1.20/' i18n/zh-cn/docusaurus-plugin-conte $SED_INPLACE 's/"version":.*/"version":"1.20-dev"/' static/latest-swagger.json -for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/current/ -name "*.md"`; do +for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/current -name "*.md"`; do # note only works on linux, forget about it when attempting to run on macos # hide hugo toc $SED_INPLACE 's/{{< toc >}}//' $file @@ -45,7 +45,7 @@ for file in i18n/zh-cn/docusaurus-plugin-content-docs/current/*; do rm $file done -for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/current/ -name "*.zh-cn.md"`; do +for file in `find ./i18n/zh-cn/docusaurus-plugin-content-docs/current -name "*.zh-cn.md"`; do mv "${file}" "${file/.zh-cn/}" done diff --git a/loop_docs.sh b/loop_docs.sh index 50b74e22..83fd4fad 100644 --- a/loop_docs.sh +++ b/loop_docs.sh @@ -21,7 +21,7 @@ $SED_INPLACE 's/{{< min-go-version >}}/1.20/' docs/installation/from-source.en-u $SED_INPLACE 's/"version":.*/"version":"1.20-dev"/' static/latest-swagger.json -for file in `find ./docs/ -name "*.md"`; do +for file in `find ./docs -name "*.md"`; do # hide hugo toc $SED_INPLACE 's/{{< toc >}}//' $file $SED_INPLACE 's/dl.gitea.com\/gitea\/{{< version >}}/dl.gitea.com\/gitea\/main/g' $file @@ -44,6 +44,8 @@ for file in docs/*; do rm $file || true done -for file in `find ./docs/ -name "*.en-us.md"`; do +# file names under docs/ and i18n/zh-cn/docusaurus-plugin-content-docs/current/ should be the same for docusaurus +# to recognize them as tanslated. +for file in `find ./docs -name "*.en-us.md"`; do mv "${file}" "${file/.en-us/}" done diff --git a/src/components/Outdated.js b/src/components/Outdated.js new file mode 100644 index 00000000..a44b662c --- /dev/null +++ b/src/components/Outdated.js @@ -0,0 +1,17 @@ +import React from 'react' +import Translate from '@docusaurus/Translate'; + +export default function Outdated(props) { + return ( +
+ + The content of current version is not up to date, please check latest English version, or + + + + Help us to translate + + +
+ ) +} diff --git a/src/css/custom.css b/src/css/custom.css index e8a72d7e..d12b64a4 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -37,3 +37,24 @@ [data-theme='dark'] .close { color: var(--ifm-color-white); } + +.outdated-text { + margin: 20px 0; + transition: box-shadow 300ms cubic-bezier(0.4, 0, 0.2, 1) 0ms; + border-radius: 4px; + box-shadow: none; + font-family: Roboto, Helvetica, Arial, sans-serif; + font-weight: 400; + font-size: 0.875rem; + line-height: 1.43; + letter-spacing: 0.01071em; + background-color: rgb(229, 246, 253); + display: flex; + padding: 6px 16px; + color: rgb(1, 67, 97); +} + +[data-theme='dark'] .outdated-text { + background-color: rgb(7, 19, 24); + color: rgb(184, 231, 251); +} diff --git a/src/theme/MDXContent/index.js b/src/theme/MDXContent/index.js new file mode 100644 index 00000000..74b229d2 --- /dev/null +++ b/src/theme/MDXContent/index.js @@ -0,0 +1,16 @@ +import React from 'react'; +import {MDXProvider} from '@mdx-js/react'; +import MDXComponents from '@theme/MDXComponents'; +// useDoc reference: +// https://fossies.org/linux/docusaurus/packages/docusaurus-theme-classic/src/theme/DocItem/Content/index.tsx +import {useDoc} from '@docusaurus/theme-common/internal'; +import Outdated from '@site/src/components/Outdated'; + +export default function MDXContent({children}) { + // {assets, contentTitle, frontMatter, metadata, toc} + const {frontMatter, metadata} = useDoc(); + return + {frontMatter.isOutdated && } + {children} + ; +}