Change Log¶
Helper utilities for manipulating a Zoo package changelog build for RST/Sphinx.
Zoo ChangeLog has a certain syntax which we’ll outline here.
A changelog is made up of 4 primary sections.
Type |
Token |
Description |
---|---|---|
Header |
==== |
Token Surrounds the header label, defaults to “Changelog”. |
Version |
—- |
Underlined with “—-” And Version is in the format of “{version} (year-month-day)”. |
Category |
~~~~ |
underlined with “~~~~” either “Added”, “Changes”, “Bug, “Removed” |
ChangeMessage |
- (messageTopicOrLabel) message body |
The formatted message which occurred. |
Example Changelog Output:
=========
ChangeLog
=========
1.2.13 (2022-01-2022)
---------------------
Added
~~~~~
Added - (docs) Pycharm setup documentation for zoo tools.
Added - (docs) sphinxcontrib.youtube thirdparty dependency when build docs to support youtube and vimeo links.
Bug Fixes
~~~~~~~~~
BugFix - (MayaPlugin) Fix FileNotFoundError being raised due to incorrect zoo initialization order.
- class Changelog(label)¶
Bases:
object
Interface to manage changelog versions and output rst lines via asRstLines.
- Parameters:
label (str) – The changelog header label ie. ChangeLog.
- children()¶
Returns the child versions in the order they were added.
- Return type:
iterable[
ChangelogVersion
]
- sortedVersions()¶
Returns a sorted tuple by the version. version sorting using stdlib LooseVersion instances.
- Return type:
tuple[str,
ChangelogVersion
]
- printTree()¶
Simply does a formatted print statement for visual debugging of the changelog hierarchy.
- class ChangelogVersion(version, date, changelog)¶
Bases:
object
A Single Version in the changelog which manages and sorts categories.
- Parameters:
- classmethod parseString(st, changelog)¶
- children()¶
Returns all child categories in the same order they were added.
- Return type:
list[
ChangelogCategory
]
- class ChangelogCategory(changelogVersion, label)¶
Bases:
object
Wraps a Category which contains a list of messages/changes.
- Parameters:
changelogVersion (
ChangelogVersion
) – The version instance which the category is linked too.label (str) –
- children()¶
Returns a list of messages in the order they were added.
- Return type:
list[
ChangeMessage
]
- sortMessages()¶
Sorts and returns current change messages for the category.
- Return type:
list[
ChangeMessage
]
- class ChangeMessage(label, subject, body)¶
Bases:
object
Single line message which includes a subject and body.
The output of rst is the below.:
- (subject) body
- Parameters:
- classmethod parseString(st)¶
- parseChangelog(changelog)¶
Providing a changelog as a raw string this function will return a changelog instance.
- parseChangeLogFile(f)¶
Providing a changelog File object will generate a Changelog instance.
- Parameters:
f (
file
) – The file instance- Return type:
- createRstTitle(beforeToken, title, afterToken)¶
Generates Rst title based on the before and after title
# creates the below ignoring "#" # ------- # myTitle # ------- createRstTitle("-", "myTitle", "-") # creates the below ignoring "#" # myTitle # ------- createRstTitle(None, "myTitle", "-")
- parseCategory(cat)¶
Converts a category label ie. bug to a standardized name for the rst changelog.
- iterChangelog(node)¶
Generator function which iterators the change log starting from node
- Parameters:
node (
Changelog
orChangelogVersion
or ChangelogCategory or ChangelogMessage) –- Returns:
- Return type:
list[
Changelog
orChangelogVersion
or ChangelogCategory or ChangelogMessage]