Add release notes functionality

Author: choldgraf

docs/index.md

@@ -57,7 +57,7 @@ You can find the [resulting markdown here](sample_notebook_activity).
 For repositories that use multiple branches, it may be necessary to filter PRs by a branch name.  This can be done using the `--branch` parameter in the CLI.   Other git references can be used as well in place of a branch name.
 ```
 
-### Splitting PRs by tags and prefixes
+### Split PRs by tags and prefixes
 
 Often you wish to split your PRs into multiple categories so that they are easier
 to scan and parse. You may also _only_ want to keep some PRs (e.g. features, or API
@@ -80,6 +80,22 @@ You can choose to *remove* some types of PRs from your changelog by passing the
 left-most column above.
 ```
 
+## Pull release notes from PR descriptions
+
+You can optionally include snippets of release notes directly from the descriptions of Pull Requests.
+These will be included just underneath the bullet point text for each PR in the markdown output.
+
+To do so, follow these steps:
+
+1. In your PR description, include a markdown header that begins with `# Release notes`.
+   The header can be of any level, and capitalization does not matter.
+   All subsequent text in the PR description will be treated as the release notes, until a header of equal or lesser level is encountered.
+2. Use the `--include-release-notes` flag. For example:
+
+   ```
+   github-activity --include-release-notes
+   ```
+
 ## Use a GitHub API token
 
 `github-activity` uses the GitHub API to pull information about a repository's activity.

github_activity/github_activity.py

@@ -5,11 +5,11 @@
 import shlex
 import subprocess
 import sys
-import urllib
 from pathlib import Path
 from subprocess import PIPE
 from subprocess import run
 from tempfile import TemporaryDirectory
+from textwrap import indent
 
 import dateutil
 import numpy as np
@@ -548,20 +548,24 @@ def generate_activity_md(
 
                 # Search the description for release notes and add them if they exist
                 if include_release_notes:
-                    lines = description.split("\n")
-                    headers = [ii.startswith("#") for ii in lines]
-                    release_notes = [ii for ii in headers if "# release notes" in ii.lower()]
+                    release_notes = []
+                    in_release_notes = False
+                    for ii in description.split("\n"):
+                        if in_release_notes:
+                            # If we detect a header of equal or lesser level, stop looking
+                            if ii.startswith("#") and len(ii.split(" ")[0]) <= n_levels:
+                                break
+                            # Otherwise append the line and keep going
+                            release_notes.append(ii)
+                        elif "# release notes" in ii.lower():
+                            # When we detect a release notes header,
+                            # start collecting lines underneath and define the header
+                            # level so we know when to stop
+                            in_release_notes = True
+                            n_levels = len(ii.split(" ")[0])
+
                     if release_notes:
-                        # Find the line of the next header to know when to stop
-                        release_notes_line = release_notes[0]
-                        next_header_ix = headers.index(release_notes_line) + 1
-                        next_header = headers[next_header_ix]
-                        release_notes_start = lines.index(release_notes_line)
-                        release_notes_stop = lines.index(next_header)
-
-                        # Append the release notes to our output markdown
-                        release_notes = "\n".join(lines[release_notes_start:release_notes_stop])
-                        this_md += f"\n   {release_notes}"
+                        this_md += "\n\n" + indent("\n".join(release_notes).strip(), "  ")
                 items["md"].append(this_md)
 
     # Get functional GitHub references: any git reference or master@{YY-mm-dd}

tests/test_cli.py

@@ -80,3 +80,19 @@ def test_cli_all(tmpdir, file_regression):
     md = path_output.read_text()
     index = md.index("## v0.2.0")
     file_regression.check(md[index:], extension=".md")
+
+
+def test_release_notes(tmpdir, file_regression):
+    """Release notes that are automatically pulled from PR descriptions."""
+    path_tmp = Path(tmpdir)
+    path_output = path_tmp.joinpath("out.md")
+    url = "https://github.com/executablebooks/jupyter-book"
+
+    # This release range covers PRs with 
+    cmd = f"github-activity {url} -s v0.7.1 -u v0.7.3 --include-release-notes -o {path_output}"
+
+    run(cmd.split(), check=True)
+
+    md = path_output.read_text()
+    test_md = md[md.index("## New features added"): md.index("## Bugs fixed")]
+    file_regression.check(test_md, extension=".md")

tests/test_cli/test_release_notes.md

@@ -0,0 +1,40 @@
+## New features added
+
+- ✨ NEW: Adding - chapter entries to _toc.yml [#817](https://github.com/executablebooks/jupyter-book/pull/817) ([@choldgraf](https://github.com/choldgraf))
+
+  Here's an example of the TOC structure:
+
+  ```yaml
+  - file: intro
+    numbered: true
+
+  - chapter: Get started
+    sections:
+    - file: start/overview
+    - file: start/build
+
+  - chapter: Book pages and types
+    sections:
+    - file: content/markdown
+    - file: content/notebooks
+
+  - chapter: Reference and test pages
+    sections:
+    - file: test_pages/test
+      sections:
+        - file: test_pages/layout_elements
+        - file: test_pages/equations
+  ```
+
+## Enhancements made
+
+- 👌 IMPROVE: improving numbered sections [#826](https://github.com/executablebooks/jupyter-book/pull/826) ([@choldgraf](https://github.com/choldgraf))
+- checking for toc modification time [#772](https://github.com/executablebooks/jupyter-book/pull/772) ([@choldgraf](https://github.com/choldgraf))
+
+  This is an attempt at checking for the modification time of the table of contents file and forcing a re-build of all pages if this happens. We need to do this because otherwise people could change the toc, but Sphinx won't know to re-build some pages and these TOC changes won't be reflected.
+
+  #### This heading will be included in release notes
+
+  Here's a sub-heading
+- first pass toc directive [#757](https://github.com/executablebooks/jupyter-book/pull/757) ([@choldgraf](https://github.com/choldgraf))
+