变更日志 0.6.1

配置

conf.py中的配置示例如下

extensions = [
            # changelog extension
            'changelog',

            # your other sphinx extensions
            # ...
        ]


# section names - optional
changelog_sections = ["general", "rendering", "tests"]

# section css classes - optional
changelog_caption_class = "caption"

# tags to sort on inside of sections - also optional
changelog_inner_tag_sort = ["feature", "bug"]

# whether sections should be hidden from tags list
changelog_hide_sections_from_tags = False

# whether tags should be hidden from entries
changelog_hide_tags_in_entry = False

# how to render changelog links - these are plain
# python string templates, ticket/pullreq/changeset number goes
# in "%s"
changelog_render_ticket = "http://bitbucket.org/myusername/myproject/issue/%s"
changelog_render_pullreq = "http://bitbucket.org/myusername/myproject/pullrequest/%s"
changelog_render_changeset = "http://bitbucket.org/myusername/myproject/changeset/%s"

用法

变更日志引入了changelog和change指令

====================
Changelog for 1.5.6
====================

.. changelog::
    :version: 1.5.6
    :released: Sun Oct 12 2008

    .. change::
        :tags: general
        :tickets: 27

      Improved the frobnozzle.

    .. change::
        :tags: rendering, tests
        :pullreq: 8
        :changeset: a9d7cc0b56c2

      Rendering tests now correctly render.

使用上述标记，上述变更将被渲染为每个变更日志的文档部分，然后每个变更组织到段落中，包括对标签、提到的票证、拉取请求、更改集的特殊标记。条目将根据changelog_sections和changelog_inner_tag_sort配置进行分组和排序。

如果配置中有一个类似于这样的部分，也可以使用“复合标签”

changelog_sections = ["orm declarative", "orm"]

然后包含orm和declarative标签的变更条目将分组在名为orm declarative的部分下，之后是orm部分，其中仅包含orm的变更条目将被放置。

其他标记

:ticket:指令将使用changelog_render_ticket标记来渲染票证链接

:ticket:`456`

尚未记录的其他事项

• ":version:" 指令，表示应将更改日志条目列在其他版本中

• ":changelog_imports:" 指令 - 读取其他 changelog.rst 文件，寻找适用于当前更改日志文件的 ":version:" 指令，并将这些条目添加到当前文件的更改日志条目中

• ":include_notes_from:" 符号 - 将目录中的所有 .rst 文件导入到当前文件中，以便每个文件更改一次，使得 git 合并成为可能

• 在发布时收集上述按文件更改的 .rst 文件的 "changelog release-notes" 命令，并将其渲染为主要的 changelog.rst 文件，对单个文件运行 "git rm" 命令

• changelog.rst -> markdown 转换器，用于需要将更改日志部分写成 markdown 的 web 界面

• changelog.rst -> 每个更改日志 markdown API 函数的流，例如可以将每个发布的更改日志流式传输到 github 发布 API