Merge pull request #2097 from strictdoc-project/stanislaw/docs

 docs: update release notes and Docker instructions

Author: stanislaw

docs/strictdoc_01_user_guide.sdoc

@@ -267,25 +267,59 @@ TITLE: Installing StrictDoc into a Docker container
 [TEXT]
 MID: 32e04944c2a14ead93248ff1ea37a68d
 STATEMENT: >>>
-StrictDoc can be invoked inside of a Docker container. To make data available
-to the Docker container (here: ``strictdoc:latest``) as well as to the host
-system, one needs to mount a volume via ``-v`` option.
+StrictDoc can be installed with a dedicated Docker image.
 
-In the host operating system terminal:
+To build the image:
 
 .. code-block:: text
 
-    docker build . -t strictdoc:latest
-    docker run --name strictdoc --rm -v "$(pwd)/docs:/data" -i -t strictdoc:latest
+    docker build . \
+        --build-arg STRICTDOC_SOURCE=pypi \
+        -t strictdoc:latest
 
-In the container terminal:
+The ``STRICTDOC_SOURCE`` argument is optional (default value is ``pypi``) and can be used to specify which Git revision the container shall check out when installing StrictDoc with ``pip install``. Possible values: a branch name, e.g., ``main``, or a commit hash.
+
+To run the container:
+
+.. code-block:: text
+
+    docker run \
+        --name strictdoc \
+        --rm \
+        -e HOST_UID=$(id -u) \
+        -e HOST_GID=$(id -g) \
+        -v "$(pwd):/data" \
+        -i -t \
+        strictdoc:latest \
+        /bin/bash -c "strictdoc export --formats=html"
+
+.. list-table:: ``docker run`` options breakdown
+   :widths: 40 60
+   :header-rows: 1
+
+   * - **Option**
+     - **Description**
+
+   * - ``--rm``
+     - Remove container when it is exited.
+
+   * - ``HOST_UID`` and ``HOST_GID``
+     - These environment variables are used to tell the container that it should create a ``strictdoc`` user that has these values. This enables the content generated by the container to be visible outside the container under the permissions of the host user.
+
+   * - ``-v "<folder on host>:/data"``
+     - Normally the folder on the host should be the folder with the StrictDoc documentation. The ``/data`` folder must always be specified without change because that's where the Docker container is designed to operate.
+
+   * - ``/bin/bash -c "..."``
+     - This command shall typically be ``strictdoc export`` but it can also be skipped in which case the ``docker run`` will enter the container with SSH.
+
+If entering the container manually, the ``strictdoc`` command can be run as follows:
 
 .. code-block:: text
 
     bash-5.1# strictdoc export .
     bash-5.1# exit
 
-The documentation resides in ``./docs/output/html``.
+The documentation shall be generated to ``./output/html`` which is accessible both on the host and inside the container.
 <<<
 
 [/SECTION]

docs/strictdoc_04_release_notes.sdoc

@@ -33,7 +33,17 @@ TITLE: Unreleased work
 [TEXT]
 MID: c5725f24fcd24d54929e155f6ad47b44
 STATEMENT: >>>
-The autocompletion dropdown has been added to the relation editor in the Web GUI. Thanks to @thseiler for contributing this work.
+This release includes the following enhancements.
+
+The autocompletion dropdown has been added to the relation editor in the Web GUI. [@thseiler]
+
+Link anchors are no longer generated using section numbers, which improves their stability when StrictDoc documentation is linked from external sources. If a requirement is moved to another section within the same document, the original link will still correctly resolve to the UID [@thseiler].
+
+The legacy FREETEXT parsing has been completely removed from Document and Section. The [FREETEXT] marker is no longer recognized by StrictDoc, allowing for the removal of a significant amount of legacy code.
+
+Based on user feedback, the StrictDoc's Dockerfile now supports the HTML2PDF feature. The container file was refactored to be based on Ubuntu 24 which is the default Linux platform for StrictDoc development and testing. The image installs Google Chrome which enables the HTML2PDF to work out of the box without any other installation steps.
+
+Over the years, StrictDoc has been transitioning to a 100% statically-typed codebase. As part of the ongoing refactoring of StrictDoc's type system, more type annotations have been added to the core StrictDoc model classes (Document, Node, Section, DocumentFromFile, etc.). These improvements should further reduce the risk of future regressions due to stronger static type checking.
 <<<
 
 [/SECTION]

tasks.py

@@ -889,9 +889,14 @@ def test_docker(context, image: str = "strictdoc:latest"):
         image=image,
         command="strictdoc export --formats=html,html2pdf .",
     )
-    run_invoke(
-        context,
-        """
-        [ "$(stat -c "%U" output/html2pdf/pdf/docs/strictdoc_01_user_guide.pdf)" = "$(whoami)" ]
-        """,
+
+    def check_file_owner(filepath):
+        import pwd
+
+        file_owner = pwd.getpwuid(os.stat(filepath).st_uid).pw_name
+        current_user = os.environ.get("USER", "")
+        return file_owner == current_user
+
+    assert check_file_owner(
+        "output/html2pdf/pdf/docs/strictdoc_01_user_guide.pdf"
     )