docs(changelog): add formatted changelog into hosted documentation (#1155)

* chore(changelog): configure custom release notes & RST changelog for PSR

* chore(changelog): convert project changelog to an updating RST

Author: codejedi365

CHANGELOG.md

@@ -0,0 +1,254 @@
+{#
+    This file overrides what would be generated normally because the commits are
+    not conformative to the standard commit message format.
+#}
+.. _changelog-v1.0.0:
+
+v1.0.0 (2015-08-04)
+===================
+
+💥 Breaking
+-----------
+
+* Restructure helpers into history and pypi (`00f64e6`_)
+
+📖 Documentation
+----------------
+
+* Add automatic publishing documentation, resolves `#18`_ (`58076e6`_)
+
+.. _#18: https://github.com/python-semantic-release/python-semantic-release/issues/18
+.. _00f64e6: https://github.com/python-semantic-release/python-semantic-release/commit/00f64e623db0e21470d55488c5081e12d6c11fd3
+.. _58076e6: https://github.com/python-semantic-release/python-semantic-release/commit/58076e60bf20a5835b112b5e99a86c7425ffe7d9
+
+
+.. _changelog-v0.9.1:
+
+v0.9.1 (2015-08-04)
+===================
+
+🪲 Bug Fixes
+------------
+
+* Fix ``get_current_head_hash`` to ensure it only returns the hash (`7c28832`_)
+
+.. _7c28832: https://github.com/python-semantic-release/python-semantic-release/commit/7c2883209e5bf4a568de60dbdbfc3741d34f38b4
+
+
+.. _changelog-v0.9.0:
+
+v0.9.0 (2015-08-03)
+===================
+
+✨ Features
+-----------
+
+* Add Python 2.7 support, resolves `#10`_ (`c05e13f`_)
+
+.. _#10: https://github.com/python-semantic-release/python-semantic-release/issues/10
+.. _c05e13f: https://github.com/python-semantic-release/python-semantic-release/commit/c05e13f22163237e963c493ffeda7e140f0202c6
+
+
+.. _changelog-v0.8.0:
+
+v0.8.0 (2015-08-03)
+===================
+
+✨ Features
+-----------
+
+* Add ``check_build_status`` option, resolves `#5`_ (`310bb93`_)
+
+* Add ``get_current_head_hash`` in git helpers (`d864282`_)
+
+* Add git helper to get owner and name of repo (`f940b43`_)
+
+.. _#5: https://github.com/python-semantic-release/python-semantic-release/issues/5
+.. _310bb93: https://github.com/python-semantic-release/python-semantic-release/commit/310bb9371673fcf9b7b7be48422b89ab99753f04
+.. _d864282: https://github.com/python-semantic-release/python-semantic-release/commit/d864282c498f0025224407b3eeac69522c2a7ca0
+.. _f940b43: https://github.com/python-semantic-release/python-semantic-release/commit/f940b435537a3c93ab06170d4a57287546bd8d3b
+
+
+.. _changelog-v0.7.0:
+
+v0.7.0 (2015-08-02)
+===================
+
+✨ Features
+-----------
+
+* Add ``patch_without_tag`` option, resolves `#6`_ (`3734a88`_)
+
+📖 Documentation
+----------------
+
+* Set up sphinx based documentation, resolves `#1`_ (`41fba78`_)
+
+.. _#1: https://github.com/python-semantic-release/python-semantic-release/issues/1
+.. _#6: https://github.com/python-semantic-release/python-semantic-release/issues/6
+.. _3734a88: https://github.com/python-semantic-release/python-semantic-release/commit/3734a889f753f1b9023876e100031be6475a90d1
+.. _41fba78: https://github.com/python-semantic-release/python-semantic-release/commit/41fba78a389a8d841316946757a23a7570763c39
+
+
+.. _changelog-v0.6.0:
+
+v0.6.0 (2015-08-02)
+===================
+
+✨ Features
+-----------
+
+* Add twine for uploads to pypi, resolves `#13`_ (`eec2561`_)
+
+.. _#13: https://github.com/python-semantic-release/python-semantic-release/issues/13
+.. _eec2561: https://github.com/python-semantic-release/python-semantic-release/commit/eec256115b28b0a18136a26d74cfc3232502f1a6
+
+
+.. _changelog-v0.5.4:
+
+v0.5.4 (2015-07-29)
+===================
+
+🪲 Bug Fixes
+------------
+
+* Add python2 not supported warning (`e84c4d8`_)
+
+.. _e84c4d8: https://github.com/python-semantic-release/python-semantic-release/commit/e84c4d8b6f212aec174baccd188185627b5039b6
+
+
+.. _changelog-v0.5.3:
+
+v0.5.3 (2015-07-28)
+===================
+
+⚙️ Build System
+---------------
+
+* Add ``wheel`` as a dependency (`971e479`_)
+
+.. _971e479: https://github.com/python-semantic-release/python-semantic-release/commit/971e4795a8b8fea371fcc02dc9221f58a0559f32
+
+
+.. _changelog-v0.5.2:
+
+v0.5.2 (2015-07-28)
+===================
+
+🪲 Bug Fixes
+------------
+
+* Fix python wheel tag (`f9ac163`_)
+
+.. _f9ac163: https://github.com/python-semantic-release/python-semantic-release/commit/f9ac163491666022c809ad49846f3c61966e10c1
+
+
+.. _changelog-v0.5.1:
+
+v0.5.1 (2015-07-28)
+===================
+
+🪲 Bug Fixes
+------------
+
+* Fix push commands (`8374ef6`_)
+
+.. _8374ef6: https://github.com/python-semantic-release/python-semantic-release/commit/8374ef6bd78eb564a6d846b882c99a67e116394e
+
+
+.. _changelog-v0.5.0:
+
+v0.5.0 (2015-07-28)
+===================
+
+✨ Features
+-----------
+
+* Add setup.py hook for the cli interface (`c363bc5`_)
+
+.. _c363bc5: https://github.com/python-semantic-release/python-semantic-release/commit/c363bc5d3cb9e9a113de3cd0c49dd54a5ea9cf35
+
+
+.. _changelog-v0.4.0:
+
+v0.4.0 (2015-07-28)
+===================
+
+✨ Features
+-----------
+
+* Add publish command (`d8116c9`_)
+
+.. _d8116c9: https://github.com/python-semantic-release/python-semantic-release/commit/d8116c9dec472d0007973939363388d598697784
+
+
+.. _changelog-v0.3.2:
+
+v0.3.2 (2015-07-28)
+===================
+
+* No change
+
+
+.. _changelog-v0.3.1:
+
+v0.3.1 (2015-07-28)
+===================
+
+🪲 Bug Fixes
+------------
+
+* Fix wheel settings (`1e860e8`_)
+
+.. _1e860e8: https://github.com/python-semantic-release/python-semantic-release/commit/1e860e8a4d9ec580449a0b87be9660a9482fa2a4
+
+
+.. _changelog-v0.3.0:
+
+v0.3.0 (2015-07-27)
+===================
+
+✨ Features
+-----------
+
+* Add support for tagging releases (`5f4736f`_)
+
+🪲 Bug Fixes
+------------
+
+* Fix issue when version should not change (`441798a`_)
+
+.. _441798a: https://github.com/python-semantic-release/python-semantic-release/commit/441798a223195138c0d3d2c51fc916137fef9a6c
+.. _5f4736f: https://github.com/python-semantic-release/python-semantic-release/commit/5f4736f4e41bc96d36caa76ca58be0e1e7931069
+
+
+.. _changelog-v0.2.0:
+
+v0.2.0 (2015-07-27)
+===================
+
+✨ Features
+-----------
+
+* added no-operation (``--noop``) mode (`44c2039`_)
+
+⚙️ Build System
+---------------
+
+* Swapped pygit2 with gitpython to avoid libgit2 dependency (`8165a2e`_)
+
+.. _44c2039: https://github.com/python-semantic-release/python-semantic-release/commit/44c203989aabc9366ba42ed2bc40eaccd7ac891c
+.. _8165a2e: https://github.com/python-semantic-release/python-semantic-release/commit/8165a2eef2c6eea88bfa52e6db37abc7374cccba
+
+
+.. _changelog-v0.1.1:
+
+v0.1.1 (2015-07-27)
+===================
+
+🪲 Bug Fixes
+------------
+
+* Fix entry point (`bd7ce7f`_)
+
+.. _bd7ce7f: https://github.com/python-semantic-release/python-semantic-release/commit/bd7ce7f47c49e2027767fb770024a0d4033299fa

CHANGELOG.rst

@@ -0,0 +1,10 @@
+.. _changelog:
+
+{%    if ctx.changelog_mode == "update"
+%}{#    # Modified insertion flag to insert a changelog header directly
+        # which convienently puts the insertion flag incognito when reading raw RST
+#}{{
+        insertion_flag ~ "\n"
+
+}}{%  endif
+%}

config/release-templates/.components/changelog_1.0.0.rst.j2

@@ -0,0 +1,39 @@
+{#
+This changelog template initializes a full changelog for the project,
+it follows the following logic:
+  1. Header
+  2. Any Unreleased Details (uncommon)
+  3. all previous releases except the very first release
+  4. the first release
+
+#}{#
+   #    # Header
+#}{%    include "changelog_header.rst.j2"
+-%}{#
+    #   # Any Unreleased Details (uncommon)
+#}{%    include "unreleased_changes.rst.j2"
+-%}{#
+    #   # Since this is initialization, we are generating all the previous
+    #   # release notes per version. The very first release notes is specialized.
+    #   # We also have non-conformative commits, so insert manual write-ups.
+#}{%    if releases | length > 0
+%}{%      for release in releases
+%}{%        if loop.last
+%}{{          "\n"
+}}{%          include "first_release.rst.j2"
+-%}{{         "\n"
+}}{#
+#}{%        elif release.version == "1.0.0"
+%}{#          # Append 0.1.1 through 1.0.0 non-generated changelog only once
+#}{{          "\n"
+}}{%          include "changelog_1.0.0.rst.j2"
+-%}{{         "\n\n"
+}}{#
+#}{%        elif release.version > "1.0.0"
+%}{{          "\n"
+}}{%          include "versioned_changes.rst.j2"
+-%}{{         "\n"
+}}{%        endif
+%}{%      endfor
+%}{%    endif
+%}

config/release-templates/.components/changelog_header.rst.j2

@@ -0,0 +1,71 @@
+{#
+This Update changelog template uses the following logic:
+
+  1. Read previous changelog file (ex. project_root/CHANGELOG.md)
+  2. Split on insertion flag (ex. <!-- version list -->)
+  3. Print top half of previous changelog
+  3. New Changes (unreleased commits & newly released)
+  4. Print bottom half of previous changelog
+
+  Note: if a previous file was not found, it does not write anything at the bottom
+        but render does NOT fail
+
+#}{%  set prev_changelog_contents = prev_changelog_file | read_file | safe
+%}{%  set changelog_parts = prev_changelog_contents.split(insertion_flag, maxsplit=1)
+%}{#
+#}{%  if changelog_parts | length < 2
+%}{#    # insertion flag was not found, check if the file was empty or did not exist
+#}{%    if prev_changelog_contents | length > 0
+%}{#      # File has content but no insertion flag, therefore, file will not be updated
+#}{{      changelog_parts[0]
+}}{%    else
+%}{#      # File was empty or did not exist, therefore, it will be created from scratch
+#}{%      include "changelog_init.rst.j2"
+%}{%    endif
+%}{%  else
+%}{#
+   #    Previous Changelog Header
+   #      - Depending if there is header content, then it will separate the insertion flag
+   #        with a newline from header content, otherwise it will just print the insertion flag
+#}{%    set prev_changelog_top = changelog_parts[0] | trim
+%}{%    if prev_changelog_top | length > 0
+%}{{
+          "%s\n\n%s\n" | format(prev_changelog_top, insertion_flag | trim)
+
+}}{%    else
+%}{{
+          "%s\n" | format(insertion_flag | trim)
+
+}}{%    endif
+%}{#
+   #    Any Unreleased Details (uncommon)
+#}{%    include "unreleased_changes.rst.j2"
+-%}{#
+#}{%    if releases | length > 0
+%}{#      # Latest Release Details
+#}{%      set release = releases[0]
+%}{#
+#}{%      if releases | length == 1 and ctx.mask_initial_release
+%}{#        # First Release detected
+#}{{        "\n"
+}}{%-       include "first_release.rst.j2"
+-%}{{       "\n"
+}}{#
+#}{%      elif release.version.as_semver_tag() ~ " (" not in changelog_parts[1]
+%}{#        # The release version is not already in the changelog so we add it
+#}{{        "\n"
+}}{%-       include "versioned_changes.rst.j2"
+-%}{{       "\n"
+}}{#
+#}{%      endif
+%}{%    endif
+%}{#
+   #    Previous Changelog Footer
+   #      - skips printing footer if empty, which happens when the insertion_flag
+   #        was at the end of the file (ignoring whitespace)
+#}{%    set previous_changelog_bottom = changelog_parts[1] | trim
+%}{%    if previous_changelog_bottom | length > 0
+%}{{      "\n%s\n" | format(previous_changelog_bottom)
+}}{%    endif
+%}{%  endif
+%}