Merge pull request #711 from doorstop-dev/release/v3.0.1

jacebrowning · web-flow · commit 96ebab9689bb · 2025-06-09T10:18:50.000-04:00
Release v3.0.1
diff --git a/.github/workflows/change-coverage.yml b/.github/workflows/change-coverage.yml
@@ -27,7 +27,7 @@ jobs:
           python-version: "3.11"
           architecture: x64
 
-      - uses: Gr1N/setup-poetry@v8
+      - uses: Gr1N/setup-poetry@v9
 
       - name: Check system dependencies
         run: make doctor
@@ -39,7 +39,7 @@ jobs:
 
       - name: Install project dependencies
         run: make install
-      
+
       - name: Check coverage
         run: |
           TEST_INTEGRATION=true poetry run pytest doorstop --doctest-modules --cov=doorstop --cov-report=xml --cov-report=term-missing
diff --git a/.github/workflows/execute-tests.yml b/.github/workflows/execute-tests.yml
@@ -19,9 +19,8 @@ jobs:
   test:
     runs-on: ${{ inputs.os }}
     strategy:
-      fail-fast: true
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     name: Python ${{ matrix.python-version }}
 
     defaults:
@@ -46,7 +45,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
           architecture: x64
 
-      - uses: Gr1N/setup-poetry@v8
+      - uses: Gr1N/setup-poetry@v9
 
       - name: Check system dependencies
         run: make doctor
@@ -64,7 +63,7 @@ jobs:
 
       - name: Upload coverage
         uses: codecov/codecov-action@v4
-        if: ${{ inputs.os == 'ubuntu-latest' && matrix.python-version == '3.9' && github.repository == 'doorstop-dev/doorstop' }}
+        if: ${{ inputs.os == 'ubuntu-latest' && matrix.python-version == '3.9' && (github.event_name == 'push' && !startsWith(github.ref, 'refs/heads/dependabot/') || (github.event_name == 'pull_request' && !github.event.pull_request.head.repo.fork)) }}
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true
diff --git a/.tool-versions b/.tool-versions
@@ -1,2 +1,2 @@
-python 3.9.17
-poetry 1.7.1
+python 3.13.3
+poetry 2.1.1
diff --git a/.verchew.ini b/.verchew.ini
@@ -5,13 +5,13 @@ version = GNU Make
 
 [Python]
 
-cli = python3
-version = 3.9 || 3.10 || 3.11 || 3.12
+cli = python
+version = 3.9 || 3.10 || 3.11 || 3.12 || 3.13
 
 [Poetry]
 
 cli = poetry
-version = 1.7 || 1.8
+version = 2
 
 [Graphviz]
 
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -26,6 +26,7 @@
     "codecov",
     "codeql",
     "cors",
+    "coveragespace",
     "curr",
     "cust",
     "doorhole",
@@ -37,19 +38,23 @@
     "enduml",
     "evalue",
     "EXTS",
+    "frontmatter",
     "Gitter",
     "graphviz",
     "HLINE",
     "hyperref",
+    "isort",
     "itered",
     "lgpl",
     "LINESEPERATOR",
     "linkify",
     "LONGTABLE",
+    "macfsevents",
     "mkdir",
     "mkdocs",
     "mockvcs",
     "mylevel",
+    "mypy",
     "nlev",
     "nlevel",
     "nuid",
@@ -60,9 +65,15 @@
     "plev",
     "plevel",
     "puid",
+    "pydocstyle",
     "pyficache",
+    "pygments",
+    "pyinstaller",
+    "pync",
+    "pyyaml",
     "quickstart",
     "sargs",
+    "setuptools",
     "sgignores",
     "spdx",
     "textit",
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,8 @@
-# 3.0
+# 3.0.1 (2025-06-08)
+
+- Added support for Python 3.13.
+
+# 3.0 (2025-01-25)
 
 - **BREAKING:** Dropped support for Python 3.6, 3.7, and 3.8.
 - **BREAKING:** Removed `--no-body-levels` option to `doorstop publish`.
diff --git a/Makefile b/Makefile
@@ -16,7 +16,7 @@ VIRTUAL_ENV ?= .venv
 all: doctor format check test mkdocs demo ## Run all tasks that determine CI status
 
 .PHONY: dev
-dev: install .clean-test ## Continuously run all CI tasks when files chanage
+dev: install .clean-test ## Continuously run all CI tasks when files change
 	poetry run sniffer
 
 .PHONY: dev-install
@@ -53,7 +53,7 @@ $(DEPENDENCIES): poetry.lock
 
 ifndef CI
 poetry.lock: pyproject.toml
-	poetry lock --no-update
+	poetry lock
 	@ touch $@
 endif
 
@@ -69,7 +69,7 @@ format: install
 	@ echo
 
 .PHONY: check
-check: install format  ## Run formaters, linters, and static analysis
+check: install format  ## Run formatters, linters, and static analysis
 ifdef CI
 	git diff --exit-code -- '***.py'
 endif
diff --git a/bin/checksum b/bin/checksum
@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
 import hashlib
diff --git a/bin/example-adapter.wsgi b/bin/example-adapter.wsgi
@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
 #
 # Example adapter.wsgi for doorstop.
 
diff --git a/bin/verchew b/bin/verchew
@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
 # The MIT License (MIT)
diff --git a/docs/cli/publishing.md b/docs/cli/publishing.md
@@ -1,3 +1,11 @@
+# Introduction
+
+Doorstop provides flexible options for publishing your requirements documents into various formats. You can publish individual documents or the entire document hierarchy (including trace matrix) in plain text, HTML, LaTex or Markdown. Using templates, you can customize the styling of the generated documents.
+
+The publishing process preserves the contents and structure of your requirements (optionally including attributes) in a human-readable format. This document describes the process for generating these published documents.
+
+Note that published documents are not intended to be imported into Doorstop. If you want to export files to later re-import them, use the  [export command](interchange.md) instead.
+
 # Plain Text
 
 Individual documents can be displayed:
@@ -87,6 +95,75 @@ The default LaTeX template is `doorstop`, and is included with _doorstop_. The `
 # Assets
 
 In addition to the `template` folder, an `assets` folder placed next to the
-`.doorstop.yml` file for a document will also be copied in the same manner to
-the output folder. The purpose of the `assets` folder is to contain images or
-other external artifacts that can be included in the published documents.
+`.doorstop.yml` file for a document will also be copied to the output folder during publishing. The purpose of the `assets` folder is to contain images, diagrams or other external files that can be included in your published documents.
+
+```
+document_directory/
+├── .doorstop.yml
+├── assets/
+│   ├── images/
+│   │   ├── diagram1.png
+│   │   └── screenshot.jpg
+│   ├── attachments/
+│   │   └── specification.pdf
+│   └── other/
+│       └── data.csv
+└── items/
+    ├── REQ001.yml
+    └── REQ002.yml
+```
+
+To reference the assets in your document, you should use relative paths. The publishing process will maintain these references in the outputs. For example:
+
+```
+text: |
+  The system shall process input data according to the flow diagram below:
+
+  ![Data Flow Diagram](assets/images/diagram1.png)
+
+  The specification is available at [this link](assets/attachments/specification.pdf)
+```
+
+This example shows an inline image (`diagram1.png`) embedded in the HTML as an image and a download link (`specification.pdf`) for a referenced file.
+
+# Attributes
+
+Doorstop can store additional information about the requirement in "Attribute" fields. By default, the attributes are not included in the generated documents. However, you can customize which attributes appear in published outputs by updating the document's `.doorstop.yml` file.
+
+To include specific attributes in the published document, add a `publish` list under the `attributes` section in your `.doorstop.yml` file.
+
+Example:
+```
+settings:
+  digits: 3
+  prefix: SYSTEM-REQ
+  sep: '-'
+attributes:
+  publish:
+    - commentary
+    - rationale
+    - invented-by
+```
+
+In this example, three attributes will be included in the published documents:
+* `commentary` (built in attribute)
+* `rationale` (custom attribute)
+* `invented-by` (custom attribute)
+
+If the attribute is empty for the source item, the attribute caption will be omitted from the published document.
+
+The example generated markdown will look something like this:
+
+```
+### 1.2.5 SYSTEM-REQ-007 {#SYSTEM-REQ-007}
+
+Steamboat Willie **shall** whistle while he is driving his boat.
+
+| Attribute | Value |
+| --------- | ----- |
+| commentary | The song should be a happy tune |
+| rationale | Whistling will help demonstrate that Steamboat Willie is having a good time and is care-free. |
+| invented-by | Donald |
+```
+
+More information about attributes can be found in the [item](item.md#extended-item-attributes) description and [document](document.md#extended-document-attributes) extended attributes sections.
diff --git a/doorstop/core/publishers/html.py b/doorstop/core/publishers/html.py
@@ -122,7 +122,7 @@ def lines_index(self, filenames, tree=None):
 
         """
         # Tree structure
-        text = tree.draw(html_links=True) if tree else None
+        text: str = tree.draw(html_links=True) if tree else ""
         yield ""
         yield "<h3>Tree Structure:</h3>"
         yield "<pre><code>" + text + "</pre></code>"
diff --git a/doorstop/core/publishers/markdown.py b/doorstop/core/publishers/markdown.py
@@ -41,8 +41,7 @@ def create_index(self, directory, index=INDEX, extensions=(".md",), tree=None):
             path = os.path.join(directory, index)
             log.info("creating an {}...".format(index))
             lines = self.lines_index(sorted(filenames), tree=tree)
-            common.write_text(" # Requirements index", path)
-            common.write_text("\n".join(lines), path)
+            common.write_text("# Requirements index\n" + "\n".join(lines), path)
         else:
             log.warning("no files for {}".format(index))
 
diff --git a/doorstop/core/publishers/tests/test_publisher_markdown.py b/doorstop/core/publishers/tests/test_publisher_markdown.py
@@ -287,12 +287,24 @@ def test_index_no_files(self):
     def test_index_tree(self):
         """Verify an Markdown index can be created with a tree."""
         path = os.path.join(FILES, "index2.md")
-        mock_tree = MagicMock()
-        mock_tree.documents = []
+        all_documents = []
+        all_trees = []
         for prefix in ("SYS", "HLR", "LLR", "HLT", "LLT"):
             mock_document = MagicMock()
+            mock_document._attribute_defaults = {
+                "doc": {"title": f"The {prefix} document for Doorstop"}
+            }
             mock_document.prefix = prefix
-            mock_tree.documents.append(mock_document)
+            all_documents.append(mock_document)
+
+            tree = MagicMock()
+            tree.document = mock_document
+            tree.children = []
+            all_trees.append(tree)
+
+        mock_tree = all_trees[0]  # pick "SYS" as top-level tree
+        mock_tree.children = all_trees[1:]
+        mock_tree.documents = all_documents
         mock_tree.draw = lambda: "(mock tree structure)"
         mock_item = Mock()
         mock_item.uid = "KNOWN-001"
diff --git a/doorstop/core/tests/files/index.md b/doorstop/core/tests/files/index.md
@@ -1,4 +1,6 @@
+# Requirements index
 
 ### Published Documents:
+ * [index2](index2.md)
  * [published](published.md)
  * [published2](published2.md)
diff --git a/doorstop/core/tests/files/index2.md b/doorstop/core/tests/files/index2.md
@@ -1,5 +1,11 @@
- * [<MagicMock name='mock.document.prefix' id='4877746528'>](<MagicMock name='mock.document.prefix' id='4877746528'>.md) - Test document for development of _Doorstop_
+# Requirements index
+ * [SYS](SYS.md) - The SYS document for Doorstop
+   * [HLR](HLR.md) - The HLR document for Doorstop
+   * [LLR](LLR.md) - The LLR document for Doorstop
+   * [HLT](HLT.md) - The HLT document for Doorstop
+   * [LLT](LLT.md) - The LLT document for Doorstop
 
 ### Published Documents:
+ * [index2](index2.md)
  * [published](published.md)
  * [published2](published2.md)
diff --git a/doorstop/core/tests/test_common.py b/doorstop/core/tests/test_common.py
@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: LGPL-3.0-only
 
-"""Unit tests for the doorstop.common module """
+"""Unit tests for the doorstop.common module"""
 
 import unittest
 
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-#!/usr/bin/env python3`
	`1`	`+#!/usr/bin/env python`
`2`	`2`	`# -- coding: utf-8 --`
`3`	`3`
`4`	`4`	`import hashlib`