Re: [PATCH v2 2/2] doc-guide: add help documentation checktransupdate.rst

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Mon, Jun 17, 2024 at 4:32 PM Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> wrote:
>
> On Sat, 15 Jun 2024, Dongliang Mu <dzm91@xxxxxxxxxxx> wrote:
> > This commit adds help documents - Documentation/doc-guide/checktransupdate.rst
> > and Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> > for scripts/checktransupdate.py, including English and Chinese versions
> >
> > Signed-off-by: Dongliang Mu <dzm91@xxxxxxxxxxx>
> > ---
> > v1->v2: fix some issues according to Randy
> >  Documentation/doc-guide/checktransupdate.rst  | 63 +++++++++++++++++++
> >  Documentation/doc-guide/index.rst             |  1 +
> >  .../zh_CN/doc-guide/checktransupdate.rst      | 62 ++++++++++++++++++
> >  .../translations/zh_CN/doc-guide/index.rst    |  1 +
> >  4 files changed, 127 insertions(+)
> >  create mode 100644 Documentation/doc-guide/checktransupdate.rst
> >  create mode 100644 Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> >
> > diff --git a/Documentation/doc-guide/checktransupdate.rst b/Documentation/doc-guide/checktransupdate.rst
> > new file mode 100644
> > index 000000000000..4ece330882d6
> > --- /dev/null
> > +++ b/Documentation/doc-guide/checktransupdate.rst
> > @@ -0,0 +1,63 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +Check translation update
> > +==========================
> > +
> > +This script helps track the translation status of the documentation in
> > +different locales, i.e., whether the documentation is up-to-date with
> > +the English counterpart.
> > +
> > +How it works
> > +------------
> > +
> > +It uses ``git log`` command to track the latest English commit from the
> > +translation commit (order by author date) and the latest English commits
> > +from HEAD. If any differences occur, the file is considered as out-of-date,
> > +then commits that need to be updated will be collected and reported.
> > +
> > +Features implemented
> > +--------------------
> > +
> > +-  check all files in a certain locale
> > +-  check a single file or a set of files
> > +-  provide options to change output format
> > +
> > +Usage
> > +-----
>
> Why not document the argument parser and tell people ot run
> 'checktransupdate.py --help' here? Duplicating the usage here is just a
> maintenance burden.
>

Thanks, this is a good suggestion. I will modify it in the v3 patch.

> BR,
> Jani.
>
>
>
>
> > +
> > +::
> > +
> > +   checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
> > +
> > +Options
> > +~~~~~~~
> > +
> > +-  ``-l``, ``--locale``: locale to check when file is not specified
> > +-  ``--[no-]print-commits``: whether to print commits between origin and
> > +   translation
> > +-  ``--[no-]print-updated-files``: whether to print files that do no
> > +   need to be updated
> > +-  ``files``: files to check, if this option is specified, the locale
> > +   option will be ignored.
> > +
> > +Samples
> > +~~~~~~~
> > +
> > +-  ``./scripts/checktransupdate.py -l zh_CN``
> > +   This will print all the files that need to be updated in the zh_CN locale.
> > +-  ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
> > +   This will only print the status of the specified file.
> > +
> > +Then the output is something like:
> > +
> > +::
> > +
> > +    Documentation/translations/zh_CN/process/coding-style.rst       (2 commits)
> > +    commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
> > +    commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
> > +
> > +Features to be implemented
> > +----------------------------
> > +
> > +- track the translation status of files that have no translation
> > +- files can be a folder instead of only a file
> > diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
> > index 7c7d97784626..24d058faa75c 100644
> > --- a/Documentation/doc-guide/index.rst
> > +++ b/Documentation/doc-guide/index.rst
> > @@ -12,6 +12,7 @@ How to write kernel documentation
> >     parse-headers
> >     contributing
> >     maintainer-profile
> > +   checktransupdate
> >
> >  .. only::  subproject and html
> >
> > diff --git a/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> > new file mode 100644
> > index 000000000000..37c0bb518ab8
> > --- /dev/null
> > +++ b/Documentation/translations/zh_CN/doc-guide/checktransupdate.rst
> > @@ -0,0 +1,62 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +.. include:: ../disclaimer-zh_CN.rst
> > +
> > +:Original: Documentation/doc-guide/checktransupdate.rst
> > +
> > +:译者: 慕冬亮 Dongliang Mu <dzm91@xxxxxxxxxxx>
> > +
> > +检查翻译更新
> > +=============
> > +
> > +这个脚本帮助跟踪不同语言的文档翻译状态,即文档是否与对应的英文版本保持更新。
> > +
> > +工作原理
> > +------------
> > +
> > +它使用 ``git log`` 命令来跟踪翻译提交的最新英文提交(按作者日期排序)和英文文档的
> > +最新提交。如果有任何差异,则该文件被认为是过期的,然后需要更新的提交将被收集并报告。
> > +
> > +实现的功能
> > +--------------------
> > +
> > +- 检查特定语言中的所有文件
> > +- 检查单个文件或一组文件
> > +- 提供更改输出格式的选项
> > +
> > +用法
> > +-----
> > +
> > +::
> > +
> > +   checktransupdate.py [-h] [-l LOCALE] [--print-commits | --no-print-commits] [--print-updated-files | --no-print-updated-files] [--debug | --no-debug] [files ...]
> > +
> > +选项
> > +~~~~~~~
> > +
> > +-  ``-l``, ``--locale``: 检查指定的文件语言,如果未指定文件
> > +-  ``--[no-]print-commits``: 是否打印英文原始版本和翻译版本之间的提交
> > +-  ``--[no-]print-updated-files``: 是否打印无需更新的文件
> > +-  ``files``: 要检查的文件,如果指定了此选项,将忽略语言选项
> > +
> > +示例
> > +~~~~~~~
> > +
> > +-  ``./scripts/checktransupdate.py -l zh_CN``
> > +   这将打印 zh_CN 语言中需要更新的所有文件。
> > +-  ``./scripts/checktransupdate.py Documentation/translations/zh_CN/process/coding-style.rst``
> > +   这将只打印指定文件的状态。
> > +
> > +然后输出类似如下的内容:
> > +
> > +::
> > +
> > +    Documentation/translations/zh_CN/process/coding-style.rst       (2 commits)
> > +    commit 6813216bbdba ("Documentation: coding-style: ask function-like macros to evaluate parameters")
> > +    commit 185ea7676ef3 ("Documentation: coding-style: Update syntax highlighting for code-blocks")
> > +
> > +待实现的功能
> > +-------------
> > +
> > +- 跟踪没有翻译过的文件的翻译状态
> > +- 文件参数可以是文件夹而不仅仅是单个文件
> > diff --git a/Documentation/translations/zh_CN/doc-guide/index.rst b/Documentation/translations/zh_CN/doc-guide/index.rst
> > index 78c2e9a1697f..0ac1fc9315ea 100644
> > --- a/Documentation/translations/zh_CN/doc-guide/index.rst
> > +++ b/Documentation/translations/zh_CN/doc-guide/index.rst
> > @@ -18,6 +18,7 @@
> >     parse-headers
> >     contributing
> >     maintainer-profile
> > +   checktransupdate
> >
> >  .. only::  subproject and html
>
> --
> Jani Nikula, Intel
>





[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux