ENH/MNT: Add main window, real test

.github/PULL_REQUEST_TEMPLATE.md

@@ -27,3 +27,5 @@
 - [ ] New/changed functions and methods are covered in the test suite where possible
 - [ ] Test suite passes locally
 - [ ] Test suite passes on GitHub Actions
+- [ ] Ran ``docs/pre-release-notes.sh`` and created a pre-release documentation page
+- [ ] Pre-release docs include context, functional descriptions, and contributors as appropriate

conda-recipe/meta.yaml

@@ -21,12 +21,19 @@ requirements:
     - setuptools_scm
   run:
     - python >=3.9
+    - pcdsutils
+    - pyqt
+    - qtpy
 
 test:
   imports:
     - {{ import_name }}
   requires:
+    - coverage
     - pytest
+    - pytest-qt
+    - sphinx
+    - sphinx_rtd_theme
 
 about:
   home: https://github.com/pcdshub/superscore

dev-requirements.txt

@@ -1,4 +1,9 @@
 # These are required for developing the package (running the tests) but not
 # necessarily required for _using_ it.
+coverage
 pytest
 pytest-cov
+pytest-qt
+
+sphinx
+sphinx_rtd_theme

docs/pre-release-notes.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+ISSUE=$1
+shift
+DESCRIPTION=$*
+
+if [[ -z "$ISSUE" || -z "$DESCRIPTION" ]]; then
+    echo "Usage: $0 (ISSUE NUMBER) (DESCRIPTION)"
+    exit 1
+fi
+
+re_issue_number='^[1-9][0-9]*$'
+
+if ! [[ "$ISSUE" =~ $re_issue_number ]]; then
+    echo "Error: Issue number is not a number: $ISSUE"
+    echo
+    echo "This should preferably be the issue number that this pull request solves."
+    echo "We may also accept the Pull Request number in place of the issue."
+    exit 1
+fi
+
+echo "Issue: $ISSUE"
+echo "Description: $DESCRIPTION"
+
+FILENAME=source/upcoming_release_notes/${ISSUE}-${DESCRIPTION// /_}.rst
+
+pushd "$(dirname "$0")" || exit 1
+
+sed -e "s/IssueNumber Title/${ISSUE} ${DESCRIPTION}/" \
+    "source/upcoming_release_notes/template-short.rst" > "${FILENAME}"
+
+if ${EDITOR} "${FILENAME}"; then
+    echo "Adding ${FILENAME} to the git repository..."
+    git add "${FILENAME}"
+fi
+
+popd || exit 0

docs/release_notes.py

@@ -0,0 +1,114 @@
+import sys
+import time
+from collections import defaultdict
+from pathlib import Path
+
+# find the pre-release directory and release notes file
+THIS_DIR = Path(__file__).resolve().parent
+PRE_RELEASE = THIS_DIR / 'source' / 'upcoming_release_notes'
+TEMPLATE = PRE_RELEASE / 'template-short.rst'
+RELEASE_NOTES = THIS_DIR / 'source' / 'releases.rst'
+
+# Set up underline constants
+TITLE_UNDER = '#'
+RELEASE_UNDER = '='
+SECTION_UNDER = '-'
+
+
+def parse_pre_release_file(path):
+    """
+    Return dict mapping of release notes section to lines.
+
+    Uses empty list when no info was entered for the section.
+    """
+    print(f'Checking {path} for release notes.')
+    with path.open('r') as fd:
+        lines = fd.readlines()
+
+    section_dict = defaultdict(list)
+    prev = None
+    section = None
+
+    for line in lines:
+        if prev is not None:
+            if line.startswith(SECTION_UNDER * 2):
+                section = prev.strip()
+                continue
+            if section is not None and line[0] in ' -':
+                notes = section_dict[section]
+                if len(line) > 6:
+                    notes.append(line)
+                section_dict[section] = notes
+        prev = line
+
+    return section_dict
+
+
+def extend_release_notes(path, version, release_notes):
+    """
+    Given dict mapping of section to lines, extend the release notes file.
+    """
+    with path.open('r') as fd:
+        lines = fd.readlines()
+
+    new_lines = ['\n', '\n']
+    date = time.strftime('%Y-%m-%d')
+    release_title = f'{version} ({date})'
+    new_lines.append(release_title + '\n')
+    new_lines.append(len(release_title) * RELEASE_UNDER + '\n')
+    new_lines.append('\n')
+    for section, section_lines in release_notes.items():
+        if section == 'Contributors':
+            section_lines = sorted(list(set(section_lines)))
+        if len(section_lines) > 0:
+            new_lines.append(section + '\n')
+            new_lines.append(SECTION_UNDER * len(section) + '\n')
+            new_lines.extend(section_lines)
+            new_lines.append('\n')
+
+    output_lines = lines[:2] + new_lines + lines[2:]
+
+    print('Writing out release notes file')
+    for line in new_lines:
+        print(line.strip('\n'))
+    with path.open('w') as fd:
+        fd.writelines(output_lines)
+
+
+def main(version_number: str):
+    section_notes = parse_pre_release_file(TEMPLATE)
+    to_delete = []
+    for path in PRE_RELEASE.iterdir():
+        if path.name[0] in '1234567890':
+            to_delete.append(path)
+            extra_notes = parse_pre_release_file(path)
+            for section, notes in section_notes.items():
+                notes.extend(extra_notes[section])
+                section_notes[section] = notes
+
+    extend_release_notes(RELEASE_NOTES, version_number, section_notes)
+
+    print(
+        "* Wrote release notes.  Please perform the following manually:",
+        file=sys.stderr,
+    )
+    for path in to_delete:
+        print(f" git rm {path}", file=sys.stderr)
+    print(f" git add {RELEASE_NOTES}", file=sys.stderr)
+
+
+if __name__ == '__main__':
+    if len(sys.argv) != 2:
+        print(f"Usage: {sys.argv[0]} VERSION_NUMBER", file=sys.stderr)
+        sys.exit(1)
+
+    version_number = sys.argv[1]
+
+    if not version_number.startswith("v"):
+        print(
+            f"Version number should start with 'v': {version_number}",
+            file=sys.stderr
+        )
+        sys.exit(1)
+
+    main(version_number)

docs/source/upcoming_changes.rst

@@ -0,0 +1,8 @@
+Upcoming Changes
+################
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   upcoming_release_notes/[0-9]*

docs/source/upcoming_release_notes/2-enh_main_window.rst

@@ -0,0 +1,22 @@
+2 enh_main_window
+#################
+
+API Breaks
+----------
+- N/A
+
+Features
+--------
+- Adds main window widget and cli entrypoint skeleton
+
+Bugfixes
+--------
+- N/A
+
+Maintenance
+-----------
+- Updates dependencies, adds pre-release notes framework
+
+Contributors
+------------
+- tangkong

docs/source/upcoming_release_notes/template-full.rst

@@ -0,0 +1,36 @@
+IssueNumber Title
+#################
+
+Update the title above with your issue number and a 1-2 word title.
+Your filename should be issuenumber-title.rst, substituting appropriately.
+
+Make sure to fill out any section that represents changes you have made,
+or replace the default bullet point with N/A.
+
+API Breaks
+----------
+- List backwards-incompatible changes here.
+  Changes to PVs don't count as API changes for this library,
+  but changing method and component names or changing default behavior does.
+
+Features
+--------
+- List new updates that add utility to many classes,
+  provide a new base classes, add options to helper methods, etc.
+
+Bugfixes
+--------
+- List bug fixes that are not covered in the above sections.
+
+Maintenance
+-----------
+- List anything else. The intent is to accumulate changes
+  that the average user does not need to worry about.
+
+Contributors
+------------
+- List your github username and anyone else who made significant
+  code or conceptual contributions to the PR. You don't need to
+  add reviewers unless their suggestions lead to large rewrites.
+  These will be used in the release notes to give credit and to
+  notify you when your code is being tagged.

docs/source/upcoming_release_notes/template-short.rst

@@ -0,0 +1,22 @@
+IssueNumber Title
+#################
+
+API Breaks
+----------
+- N/A
+
+Features
+--------
+- N/A
+
+Bugfixes
+--------
+- N/A
+
+Maintenance
+-----------
+- N/A
+
+Contributors
+------------
+- N/A

pyproject.toml

@@ -53,4 +53,3 @@ file = "docs-requirements.txt"
 
 [tool.pytest.ini_options]
 addopts = "--cov=."
-

requirements.txt

@@ -1 +1,4 @@
 # List requirements here.
+pcdsutils
+PyQt5
+qtpy

superscore/__main__.py

@@ -0,0 +1,3 @@
+from superscore.bin.main import main
+
+main()

superscore/bin/main.py

@@ -16,7 +16,7 @@
 DESCRIPTION = __doc__
 
 
-MODULES = ("help", )
+MODULES = ("help", "ui")
 
 
 def _try_import(module):

superscore/bin/ui.py

@@ -0,0 +1,24 @@
+"""
+`superscore ui` opens up the main application window
+"""
+import argparse
+import sys
+
+from qtpy.QtWidgets import QApplication
+
+from superscore.widgets.window import Window
+
+
+def build_arg_parser(argparser=None):
+    if argparser is None:
+        argparser = argparse.ArgumentParser()
+
+    return argparser
+
+
+def main(*args, **kwargs):
+    app = QApplication(sys.argv)
+    main_window = Window()
+
+    main_window.show()
+    app.exec()

superscore/tests/test_window.py

@@ -0,0 +1,9 @@
+from pytestqt.qtbot import QtBot
+
+from superscore.widgets.window import Window
+
+
+def test_main_window(qtbot: QtBot):
+    """Pass if main window opens successfully"""
+    window = Window()
+    qtbot.addWidget(window)