History is a preprocessor that generates single linear history of releases for multiple Git repositories based on their changelog files, tags, or commits. The history may be represented as Markdown, and as RSS feed.
$ pip install foliantcontrib.history
To enable the preprocessor, add
preprocessors section in the project config:
preprocessors: - history
The preprocessor has a number of options with the following default values:
- history: repos:  revision: '' name_from_readme: false readme: README.md from: changelog merge_commits: true changelog: changelog.md source_heading_level: 1 target_heading_level: 1 target_heading_template: '[%date%] [%repo%](%link%) %version%' date_format: year_first limit: 0 rss: false rss_file: rss.xml rss_title: 'History of Releases' rss_link: '' rss_description: '' rss_language: en-US rss_item_title_template: '%repo% %version%'
List of URLs of Git repositories that it’s necessary to generate history for.
repos: - https://github.com/foliant-docs/foliant.git - https://github.com/foliant-docs/foliantcontrib.includes.git
- Revision or branch name to use. If
revisionis not specified, the default branch of the repository will be used. If you specify a revision or branch name, it will be used for all specified repositories.
- Flag that tells the preprocessor to try to use the content of the first heading of README file in each listed repository as the repo name. If the flag set to
false, or an attempt to get the first heading content is unsuccessful, the repo name will be based on the repo URL.
- Path to README file. README files must be located at the same paths in all listed repositories.
- Data source to generate history:
commits—all commits. Data sources of the same type will be used for all listed repositories.
- Flag that tells the preprocessor to include merge commits into history when
from: commitsis used.
- Path to changelog file. Changelogs must be located at the same paths in all listed repositories.
- Level of headings that precede descriptions of releases in the source Markdown content. It must be the same for all listed repositories.
- Level of headings that precede descriptions of releases in the target Markdown content of generated history.
- Template for top-level headings in the target Markdown content. You may use any characters, and the variables:
%version%—version data (content of source changelog heading, tag value, or commit hash).
- Output date format to use in the target Markdown content. If the default value
year_firstis used, the date “September 4, 2019” will be represented as
2019-09-04. If the
day_firstvalue is used, this date will be represented as
- Maximum number of items to include into the target Markdown content;
0means no limit.
- Flag that tells the preprocessor to export the history into RSS feed. Note that the parameters
limitare applied to Markdown content only, not to RSS feed content.
- Subpath to the file with RSS feed. It’s relative to the temporary working directory during building, to the directory of built project after building, and to the
rss_linkvalue in URLs.
- RSS channel title.
- RSS channel link, e.g.
https://foliant-docs.github.io/docs/. If the
rssparameter value is
rss.xml, the RSS feed URL will be
- RSS channel description.
- RSS channel language.
- Template for titles of RSS feed items. You may use any characters, and the variables:
To insert some history into Markdown content, use the
Some optional content here. <history></history> More optional content.
If no attributes specified, the values of options from the project config will be used.
You may override each config option value with the attribute of the same name. Example:
<history repos="https://github.com/foliant-docs/foliantcontrib.mkdocs.git" revision="develop" limit="5" rss="true" rss_file="some_another.xml" ... > </history>