Python工具包：Manubot - 手稿，开放和自动化

Manubot 是下一代学术出版工作流程和工具集。此存储库包含一个Python包，其中包含多个与Manubot相关的实用程序，具体请参阅下面的使用部分。包文档可在https://manubot.github.io/manubot（从Python源代码自动生成）找到。

《manubot cite》命令行界面用于检索和格式化用户提供的持久标识符（如DOI或PubMed ID）的文献计量元数据。`manubot process` 命令行界面用于准备学术论文以便Pandoc处理。`manubot process` 命令被基于 Rootstock模板 的Manubot学术论文使用，以自动化论文生成的多个方面。`manubot ai-revision` 命令用于根据一组AI生成的建议自动修订论文。有关Rootstock的更多信息，请参阅其论文使用指南。

注意：如果您想通过编辑现有论文来体验Manubot，请参阅https://github.com/manubot/try-manubot。如果您想创建新的论文，请参阅https://github.com/manubot/rootstock。

要引用Manubot项目或了解更多关于其设计和历史信息，请参阅

使用Manubot进行开放协作写作
作者：Daniel S. Himmelstein, Vincent Rubinetti, David R. Slochower, Dongbo Hu, Venkat S. Malladi, Casey S. Greene, Anthony Gitter
PLOS Computational Biology (2019-06-24) https://doi.org/c7np
DOI: 10.1371/journal.pcbi.1007128 · PMID: 31233491 · PMCID: PMC6611653

本论文的Manubot版本可在https://greenelab.github.io/meta-review/找到。

安装

如果您将《manubot》Python包作为论文存储库的一部分使用，该包的安装将通过Rootstock的环境规范进行处理。对于其他用例，此包可以通过 pip 安装。

从PyPI安装最新版本https://pypi.ac.cn/project/manubot/

pip install --upgrade manubot

或从GitHub上的源代码安装https://github.com/manubot/manubot，使用指定的commit哈希版本

COMMIT=d2160151e52750895571079a6e257beb6e0b1278
pip install --upgrade git+https://github.com/manubot/manubot@$COMMIT

使用 --upgrade 参数确保如果存在，则 pip 更新现有的 manubot 安装。

此包中的某些功能需要 Pandoc，必须在系统上单独安装。pandoc-manubot-cite 过滤器依赖于Pandoc以及panflute（一个Python包）。用户必须根据他们的Pandoc版本安装一个兼容的panflute版本。例如，在Pandoc 2.9的系统上，安装适当的panflute，例如 pip install panflute==1.12.5。

用法

安装Python包创建《manubot》命令行程序。以下是 manubot --help 中的使用信息

usage: manubot [-h] [--version] {process,cite,webpage,ai-revision} ...

Manubot: the manuscript bot for scholarly writing

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

subcommands:
  All operations are done through subcommands:

  {process,cite,webpage,ai-revision}
    process             process manuscript content
    cite                citekey to CSL JSON command line utility
    webpage             deploy Manubot outputs to a webpage directory tree
    ai-revision         revise manuscript content with language models

请注意，所有操作都是通过以下子命令完成的。

处理

《manubot process》程序是使用Manubot的主要接口。有两个必需的参数：`--content-directory` 和 `--output-directory`，分别指定内容和输出目录的路径。内容目录存储论文源文件。由Manubot生成的文件将保存在输出目录中。

一个常见的设置是创建一个包含`content`和`output`目录的论文目录。在这种设置下，您可以运行Manubot：

manubot process \
  --skip-citations \
  --content-directory=content \
  --output-directory=output

有关所有命令行参数的文档，请参阅 manubot process --help

usage: manubot process [-h] --content-directory CONTENT_DIRECTORY
                       --output-directory OUTPUT_DIRECTORY
                       [--template-variables-path TEMPLATE_VARIABLES_PATH]
                       --skip-citations [--cache-directory CACHE_DIRECTORY]
                       [--clear-requests-cache] [--skip-remote]
                       [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]

Process manuscript content to create outputs for Pandoc consumption. Performs
bibliographic processing and templating.

options:
  -h, --help            show this help message and exit
  --content-directory CONTENT_DIRECTORY
                        Directory where manuscript content files are located.
  --output-directory OUTPUT_DIRECTORY
                        Directory to output files generated by this script.
  --template-variables-path TEMPLATE_VARIABLES_PATH
                        Path or URL of a file containing template variables
                        for jinja2. Serialization format is inferred from the
                        file extension, with support for JSON, YAML, and TOML.
                        If the format cannot be detected, the parser assumes
                        JSON. Specify this argument multiple times to read
                        multiple files. Variables can be applied to a
                        namespace (i.e. stored under a dictionary key) like
                        `--template-variables-path=namespace=path_or_url`.
                        Namespaces must match the regex `[a-zA-
                        Z_][a-zA-Z0-9_]*`.
  --skip-citations      Skip citation and reference processing. Support for
                        citation and reference processing has been moved from
                        `manubot process` to the pandoc-manubot-cite filter.
                        Therefore this argument is now required. If citation-
                        tags.tsv is found in content, these tags will be
                        inserted in the markdown output using the reference-
                        link syntax for citekey aliases. Appends
                        content/manual-references*.* paths to Pandoc's
                        metadata.bibliography field.
  --cache-directory CACHE_DIRECTORY
                        Custom cache directory. If not specified, caches to
                        output-directory.
  --clear-requests-cache
  --skip-remote         Do not add the rootstock repository to the local git
                        repository remotes.
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set the logging level for stderr logging

手动引用

Manubot具有依赖用户提供的引用元数据的能力，而不是生成它。《manubot process》在内容目录中搜索包含手动提供的引用元数据的文件，这些文件匹配glob manual-references*.*。这些文件存储在Pandoc元数据的`bibliography`字段中，以便它们可以被 pandoc-manubot-cite 加载。

引用

manubot cite 是一个命令行工具，用于生成引用键的文献学元数据。该工具可以输出为 CSL JSON 项目 的元数据，或者如果使用 --render 选项，则生成格式化的参考文献。

引用键应采用 prefix:accession 格式。例如，以下示例为四个持久性标识符生成了 Markdown 格式的参考文献

manubot cite --format=markdown \
  doi:10.1098/rsif.2017.0387 pubmed:29424689 pmc:PMC5640425 arxiv:1806.05726

以下 终端录制 展示了 manubot cite 的主要功能（对于略微过时的版本）

有关更多信息，请参阅 manubot cite --help

usage: manubot cite [-h] [--output OUTPUT]
                    [--format {csljson,cslyaml,plain,markdown,docx,html,jats} | --yml | --txt | --md]
                    [--csl CSL] [--bibliography BIBLIOGRAPHY]
                    [--no-infer-prefix] [--allow-invalid-csl-data]
                    [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                    citekeys [citekeys ...]

Generate bibliographic metadata in CSL JSON format for one or more citation
keys. Optionally, render metadata into formatted references using Pandoc. Text
outputs are UTF-8 encoded.

positional arguments:
  citekeys              One or more (space separated) citation keys to
                        generate bibliographic metadata for.

options:
  -h, --help            show this help message and exit
  --output OUTPUT       Specify a file to write output, otherwise default to
                        stdout.
  --format {csljson,cslyaml,plain,markdown,docx,html,jats}
                        Format to use for output file. csljson and cslyaml
                        output the CSL data. All other choices render the
                        references using Pandoc. If not specified, attempt to
                        infer this from the --output filename extension.
                        Otherwise, default to csljson.
  --yml                 Short for --format=cslyaml.
  --txt                 Short for --format=plain.
  --md                  Short for --format=markdown.
  --csl CSL             URL or path with CSL XML style used to style
                        references (i.e. Pandoc's --csl option). Defaults to
                        Manubot's style.
  --bibliography BIBLIOGRAPHY
                        File to read manual reference metadata. Specify
                        multiple times to load multiple files. Similar to
                        pandoc --bibliography.
  --no-infer-prefix     Do not attempt to infer the prefix for citekeys
                        without a known prefix.
  --allow-invalid-csl-data
                        Allow CSL Items that do not conform to the JSON
                        Schema. Skips CSL pruning.
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set the logging level for stderr logging

Pandoc 过滤器

此软件包创建了一个名为 pandoc-manubot-cite 的 Pandoc 过滤器，提供从 Pandoc 工作流程中访问 Manubot 的按-ID 引用功能。

选项通过 Pandoc 元数据字段设置，详情请见文档中列出的选项。

usage: pandoc-manubot-cite [-h] [--input [INPUT]] [--output [OUTPUT]]
                           target_format

Pandoc filter for citation by persistent identifier. Filters are command-line
programs that read and write a JSON-encoded abstract syntax tree for Pandoc.
Unless you are debugging, run this filter as part of a pandoc command by
specifying --filter=pandoc-manubot-cite.

positional arguments:
  target_format      output format of the pandoc command, as per Pandoc's --to
                     option

options:
  -h, --help         show this help message and exit
  --input [INPUT]    path read JSON input (defaults to stdin)
  --output [OUTPUT]  path to write JSON output (defaults to stdout)

存在其他类似的 Pandoc 过滤器：pandoc-url2cite，pandoc-url2cite-hs，以及 pwcite。目前，pandoc-manubot-cite 支持最多类型的持久性标识符。我们致力于在这些过滤器和它们的语法之间创建最大的兼容性。

手动引用

手动参考文献从 references 和 bibliography Pandoc 元数据字段中加载。如果手动参考文献文件名以 .json 或 .yaml 结尾，则假定其包含 CSL 数据（即引文样式语言 JSON）。否则，格式将从扩展名推断，并使用 pandoc-citeproc --bib2json 工具 转换为 CSL JSON。手动参考文献的标准引用键从 CSL JSON 的 id 或 note 字段推断。如果没有提供前缀，例如 doi:，url: 或 raw:，则会自动添加 raw: 前缀。如果多个手动参考文献文件为相同的标准引用 id 加载元数据，则根据文件名降序排列确定优先级。

网页

manubot webpage 命令将 Manubot 输出文件填充到 webpage 目录中。

usage: manubot webpage [-h] [--checkout [CHECKOUT]] [--version VERSION]
                       [--timestamp] [--no-ots-cache | --ots-cache OTS_CACHE]
                       [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]

Update the webpage directory tree with Manubot output files. This command
should be run from the root directory of a Manubot manuscript that follows the
Rootstock layout, containing `output` and `webpage` directories. HTML and PDF
outputs are copied to the webpage directory, which is structured as static
source files for website hosting.

options:
  -h, --help            show this help message and exit
  --checkout [CHECKOUT]
                        branch to checkout /v directory contents from. For
                        example, --checkout=upstream/gh-pages. --checkout is
                        equivalent to --checkout=gh-pages. If --checkout is
                        ommitted, no checkout is performed.
  --version VERSION     Used to create webpage/v/{version} directory.
                        Generally a commit hash, tag, or 'local'. When
                        omitted, version defaults to the commit hash on CI
                        builds and 'local' elsewhere.
  --timestamp           timestamp versioned manuscripts in webpage/v using
                        OpenTimestamps. Specify this flag to create timestamps
                        for the current HTML and PDF outputs and upgrade any
                        timestamps from past manuscript versions.
  --no-ots-cache        disable the timestamp cache.
  --ots-cache OTS_CACHE
                        location for the timestamp cache (default:
                        ci/cache/ots).
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set the logging level for stderr logging

AI 辅助学术写作

manubot ai-revision 命令使用来自 OpenAI 的大语言模型来自动修订手稿并提出文本改进建议。

usage: manubot ai-revision [-h] --content-directory CONTENT_DIRECTORY
                           [--config-directory CONFIG_DIRECTORY]
                           [--model-type MODEL_TYPE]
                           [--model-kwargs key=value [key=value ...]]
                           [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]

Revise manuscript content using AI models to suggest text improvements.

options:
  -h, --help            show this help message and exit
  --content-directory CONTENT_DIRECTORY
                        Directory where manuscript content files are located.
  --config-directory CONFIG_DIRECTORY
                        Directory where AI revision configuration files are
                        located. If unspecified, disables custom
                        configuration.
  --model-type MODEL_TYPE
                        Model type used to revise the manuscript. Default is
                        GPT3CompletionModel. It can be any subclass of
                        manubot_ai_editor.models.ManuscriptRevisionModel
  --model-kwargs key=value [key=value ...]
                        Keyword arguments for the revision model (--model-
                        type), with format key=value.
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set the logging level for stderr logging

通常的调用方法是

manubot ai-revision --content-directory content/

--model-type 和 --model-kwargs 参数用于调试目的。例如，由于工具将文本分割成段落，您可能想查看段落是否被正确检测到。当使用 OpenAI API 时，该工具会产生费用，因此检查具有复杂结构的文本时这一点可能很重要。

manubot ai-revision \
  --content-directory content/ \
  --model-type DummyManuscriptRevisionModel \
  --model-kwargs add_paragraph_marks=true

开发

环境

使用以下命令创建开发环境

conda create --name manubot-dev --channel conda-forge \
  python=3.11 pandoc=2.11.3.1
conda activate manubot-dev  # assumes conda >= 4.4
pip install --editable ".[webpage,dev]"

命令

以下是开发中常用的一些命令。它们假设工作目录设置为存储库的根目录，并且已激活 conda 环境。

# run the test suite
pytest

# install pre-commit git hooks (once per local clone).
# The pre-commit checks declared in .pre-commit-config.yaml will now
# run on changed files during git commits.
pre-commit install

# run the pre-commit checks (required to pass CI)
pre-commit run --all-files

# commit despite failing pre-commit checks (will fail CI)
git commit --no-verify

# regenerate the README codeblocks for --help messages
python manubot/tests/test_readme.py

# generate the docs
portray as_html --overwrite --output_dir=docs

# process the example testing manuscript
manubot process \
  --content-directory=manubot/process/tests/manuscripts/example/content \
  --output-directory=manubot/process/tests/manuscripts/example/output \
  --skip-citations \
  --log-level=INFO

发布说明

本部分仅适用于项目维护者。GitHub Actions 部署 发布到 PyPI。

要创建新的发布版本，请在 manubot/__init__.py 中增加 __version__。然后，设置 TAG 和 OLD_TAG 环境变量

TAG=v$(python setup.py --version)

# fetch tags from the upstream remote
# (assumes upstream is the manubot organization remote)
git fetch --tags upstream main

# get previous release tag, can hardcode like OLD_TAG=v0.3.1
OLD_TAG=$(git describe --tags --abbrev=0)

以下命令可以帮助起草发布说明

# check out a branch for a pull request as needed
git checkout -b "release-$TAG"

# create release notes file if it doesn't exist
touch "release-notes/$TAG.md"

# commit list since previous tag
echo $'\n\nCommits\n-------\n' >> "release-notes/$TAG.md"
git log --oneline --decorate=no --reverse $OLD_TAG..HEAD >> "release-notes/$TAG.md"

# commit authors since previous tag
echo $'\n\nCode authors\n------------\n' >> "release-notes/$TAG.md"
git log $OLD_TAG..HEAD --format='%aN <%aE>' | sort --unique >> "release-notes/$TAG.md"

上述更新已包含在 upstream:main 中，例如在 PR 合并后，使用 GitHub 界面 创建带有新“标签版本”的发布。监控 GitHub Actions 和 PyPI 以确认发布成功部署。

目标 & 致谢

我们的目标是创建鼓励开放科学并协助可重复性的学术基础设施。因此，我们希望Manubot软件和理念被学术界和商业实体广泛采用。为此，Manubot是免费/自由和开源软件（见 LICENSE.md）。

我们想感谢所有贡献者和资助者，他们的支持使得这个项目成为可能。具体来说，Manubot的开发得到了以下机构的财务支持：

• 阿尔弗雷德·P·斯隆基金会（项目编号 G-2018-11163）资助@dhimmel。
• 戈登和贝蒂·摩尔基金会（@DDD-Moore）资助项目编号 GBMF4552，资助@cgreene。