Release 4.33

.github/workflows/sphinx.yml

@@ -17,10 +17,10 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: 3.12
           cache: pip

docs/Makefile

@@ -3,7 +3,8 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = $(shell if [ -x .venv/bin/sphinx-build ]; then echo .venv/bin/sphinx-build; else echo sphinx-build; fi)
+SPHINXAUTOBUILD = $(shell if [ -x .venv/bin/sphinx-autobuild ]; then echo .venv/bin/sphinx-autobuild; else echo sphinx-autobuild; fi)
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -16,7 +17,7 @@ help:
 
 .PHONY: watch
 watch:
-	sphinx-autobuild . _build/html
+	$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html"
 
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/about/introduction/knowledge-model.rst

@@ -9,6 +9,8 @@ While all the possibilities are defined in the knowledge model, when researchers
 
 Knowledge models are created by data stewards in the :ref:`knowledge model editor<knowledge-model-editor>`.
 
+Each knowledge model also has a source language. A published knowledge model version can have additional :ref:`locales<knowledge-model-locales>` so the same questionnaire structure can be shown in different languages. These locales cover texts that are part of the knowledge model, such as question titles, descriptions, answer labels, advice, and resource pages. They do not translate answers typed by users.
+
 Knowledge Model Structure
 =========================
 
@@ -82,7 +84,7 @@ The value question asks for a single value that users type in. There are many di
 
 The input field differs based on the value type (simple input for string, date picker for date, etc.). Some of these have a check whether the entered value is valid (such as valid email or URL) and displays a warning if not.
 
-Value Question also can have validations. Validations differ based on the value type. For example, we can set a minimum and maximum value for a number, or a minimum and maximum length for a string. For text based types (text, email, URL), we can set also use a regular expression to create validations.
+Value Question can also have validations. Validations differ based on the value type. For example, we can set a minimum and maximum value for a number, or a minimum and maximum length for a string. For text-based types (text, email, URL), we can also use a regular expression to create validations.
 
 .. _integration-question:
 
@@ -154,14 +156,14 @@ Validation is used to define some rules for the answers in Value question type.
 Reference
 ---------
 
-References are used to provide additional information for :ref:`questions<question>`. There are three types of references. :ref:`Resource page reference<resource-page>`, :ref:`URL reference<url-reference>`, and :ref:`Cross reference<cross-reference>`. resource page references are gathered in the resource collections.
+References are used to provide additional information for :ref:`questions<question>`. There are three types of references. :ref:`Resource page reference<resource-page>`, :ref:`URL reference<url-reference>`, and :ref:`Cross reference<cross-reference>`. Resource page references are gathered in the resource collections.
 
 .. _resource-collection:
 
 Resource Collection
 ^^^^^^^^^^^^^^^^^^^
 
-Resource collections are used to group together :ref:`resource pages<resource-page>` that are related to each other. Each resource collection has a **title** and has a list of resource pages. Resource collection is created on a level of a Knowledge Model.
+Resource collections are used to group together :ref:`resource pages<resource-page>` that are related to each other. Each resource collection has a **title** and has a list of resource pages. Resource collection is created on a level of a knowledge model.
 
 .. _resource-page:
 
@@ -241,7 +243,7 @@ Integrations define a connection to an external service or resource where we can
 API Integration
 ^^^^^^^^^^^^^^^
 
-API integration connects to an external service API to search for the answers. We need to provide some **request** and **response** configuration, so |project_name| can use the API.
+API integration connects to an external service API to search for the answers. We need to provide some **request** and **response** configuration, so DSW can use the API.
 
 
 .. _annotations:

docs/about/introduction/project.rst

@@ -23,7 +23,7 @@ The questionnaire is part of the project where we fill in our answers. It is gen
 Documents
 =========
 
-The outcome of our endeavors in |project_name| should be the data management plan, the document. Once we have enough answers to the questionnaire, we can generate a document using a document template. These documents are saved within the project. We can create as many as we wish with different document templates and formats. We can also set up a default document template for the project and quickly see a preview of the document.
+The outcome of our endeavors in DSW should be the data management plan, the document. Once we have enough answers to the questionnaire, we can generate a document using a document template. These documents are saved within the project. We can create as many as we wish with different document templates and formats. We can also set up a default document template for the project and quickly see a preview of the document.
 
 
 :ref:`Learn how to work with the documents →<project-documents>`

docs/application/administration/index.rst

@@ -3,7 +3,7 @@
 Administration
 **************
 
-Administration section serves as the name suggests to admins with managing the |project_name| instance. By navigating via :guilabel:`Administration` item from the main menu, we can manage the things listed below.
+Administration section serves as the name suggests to users with permission to manage the DSW instance. By navigating via :guilabel:`Administration` item from the main menu, we can manage the things listed below.
 
 ----
 
@@ -16,5 +16,6 @@ Administration section serves as the name suggests to admins with managing the |
     :maxdepth: 2
 
     settings/index
+    roles/index
     users/index
     locales/index

docs/application/administration/locales/create.rst

@@ -1,17 +1,16 @@
 Create Locale
 *************
 
-We can create a new locale directly in |project_name| by pressing :guilabel:`Create` from :doc:`./index`. We need to fill the details about the new locale such as name, description, language code (`RFC5646 <https://www.rfc-editor.org/rfc/rfc5646.html>`__, e.g. ``en`` or ``en-GB``), locale ID, locale version, license, README (with Markdown syntax), and recommended app version. The recommended app version captures for which version of the |project_name| is this locale intended and compatible with (it can be used in other versions as well but may have some untranslated texts).
+We can create a new locale directly in DSW by pressing :guilabel:`Create` from :doc:`./index`. We need to fill the details about the new locale such as name, description, language code (`RFC5646 <https://www.rfc-editor.org/rfc/rfc5646.html>`__, e.g. ``en`` or ``en-GB``), locale ID, locale version, license, README (with Markdown syntax), and recommended app version. The recommended app version captures for which version of the DSW is this locale intended and compatible with (it can be used in other versions as well but may have some untranslated texts).
 
 Finally, a PO file is requested from us. We can create such PO file in a standard (`gettext <https://www.gnu.org/software/gettext/>`__-based) way.
 
 Similarly we can create a PO file for the emails.
 
 The needed POT files are placed in the localization repository `wizard-locales <https://github.com/ds-wizard/wizard-locales>`__ (select the desired release and there is ``default.pot`` asset).
 
-Recommended tool for creating the localization is the `Poedit <https://poedit.net/>`__.
+Recommended tool for creating the localization is the `Poedit <https://poedit.com/>`__.
 
 .. figure:: create/form.png
 
     Form for creating a new locale.
-

docs/application/administration/locales/detail.rst

@@ -1,7 +1,7 @@
 Locale Detail
 *************
 
-The detail of a locale provides us information about a locale after navigating to it from :doc:`./index`. The detail shows basic information about the locale such as its name, ID, language code (`RFC5646 <https://www.rfc-editor.org/rfc/rfc5646.html>`__, e.g. ``en`` or ``en-GB``), version, recommended compatible |project_name| version, license, and indication whether the locale is enabled or not.
+The detail of a locale provides us information about a locale after navigating to it from :doc:`./index`. The detail shows basic information about the locale such as its name, ID, language code (`RFC5646 <https://www.rfc-editor.org/rfc/rfc5646.html>`__, e.g. ``en`` or ``en-GB``), version, recommended compatible DSW version, license, and indication whether the locale is enabled or not.
 
 The main part of the detail is the README of the locale that should contain basic information and changelog. In the right panel under the basic information, we can navigate to other versions of the locale.
 

docs/application/administration/locales/import.rst

@@ -3,15 +3,15 @@
 Import Locale
 *************
 
-We can import an existing locale by navigating to :menuselection:`Settings → Locales` in the main menu and then clicking on :guilabel:`Import` button on the list of locales.
+We can import an existing locale by navigating to :menuselection:`Administration → Locales` in the main menu and then clicking on :guilabel:`Import` button on the list of locales.
 
 
 .. _locale-import-from-registry:
 
 From DSW Registry
 =================
 
-If the |project_name| instance is connected to the `DSW Registry <https://registry.ds-wizard.org>`__, it is possible to import locales from it by entering the **locale ID** of desired template (e.g. ``dsw:cs:0.2.0``) and pressing the :guilabel:`Import` button.
+If the DSW instance is connected to the `DSW Registry <https://registry.ds-wizard.org>`__, it is possible to import locales from it by entering the **locale ID** of desired template (e.g. ``dsw:cs:0.2.0``) and pressing the :guilabel:`Import` button.
 
 .. NOTE::
 
@@ -28,10 +28,9 @@ If the |project_name| instance is connected to the `DSW Registry <https://regist
 From file
 =========
 
-We can import a locale as a ZIP package. Such a package can be created as an export from |project_name|. We can also select multiple files at once.
+We can import a locale as a ZIP package. Such a package can be created as an export from DSW. We can also select multiple files at once.
 
 .. figure:: import/file.png
     :width: 500
 
     Input for importing a locale using a ZIP package.
-

docs/application/administration/locales/index.rst

@@ -1,13 +1,15 @@
 Locales
 *******
 
-After navigating to :guilabel:`Locales` (under :guilabel:`Administration`), we can browse and manage a list of locales in the |project_name| instance. Similarly to knowledge models and document templates, each locale has its unique identifier and version. Moreover, each locale has a language code specified. In the list we see the latest version and can quickly navigate to :doc:`./detail` (which includes also older versions) by clicking the locale name or selecting :guilabel:`View detail` from the right item menu of the desired row.
+After navigating to :guilabel:`Locales` (under :guilabel:`Administration`), we can browse and manage a list of locales in the DSW instance. Similarly to knowledge models and document templates, each locale has its unique identifier and version. Moreover, each locale has a language code specified. In the list we see the latest version and can quickly navigate to :doc:`./detail` (which includes also older versions) by clicking the locale name or selecting :guilabel:`View detail` from the right item menu of the desired row.
 
-The |project_name| UI and emails can be localized to different languages. The preferred language is determined by the user's browser settings or by the user's profile settings.
+The DSW UI and emails can be localized to different languages. The preferred language is determined by the user's browser settings or by the user's profile settings.
+
+These locales are used for the DSW user interface and emails. They are separate from :ref:`knowledge model locales<knowledge-model-locales>`, which translate questionnaire content provided by a knowledge model.
 
 .. NOTE::
 
-    Locales can be used not only for translations but also for customizing the |project_name| to a specific domain.
+    Locales can be used not only for translations but also for customizing the DSW to a specific domain.
 
 
 There is always the **English** locale (``~:default:1.0.0``) which is embedded and cannot be deleted. For others, we can use :guilabel:`Export` and :guilabel:`Delete` options from the right item menu.
@@ -19,7 +21,7 @@ If there is a locale with newer version available in the `DSW Registry <https://
 
 .. NOTE ::
 
-    We support community of DSW translators by managing the repository `ds-wizard/wizard-client-locales <https://github.com/ds-wizard/wizard-client-locales>`__ and service for translating using web browser `localize.ds-wizard.org <https://localize.ds-wizard.org>`__.
+    We support community of DSW translators by managing the repository `ds-wizard/wizard-locales <https://github.com/ds-wizard/wizard-locales>`__ and service for translating using web browser `localize.ds-wizard.org <https://localize.ds-wizard.org>`__.
 
 .. figure:: index/list.png
 
@@ -39,4 +41,4 @@ If there is a locale with newer version available in the `DSW Registry <https://
 
     Import<import>
     Create<create>
-    Detail<detail>
+    Detail<detail>

docs/application/administration/roles/index.rst

@@ -0,0 +1,105 @@
+.. _roles:
+
+Roles
+*****
+
+Roles define what users can do across the DSW instance. Each user has one global role. The role contains a set of permissions, such as whether the user can manage users, configure settings, work with knowledge models, or access all projects.
+
+Default Roles
+=============
+
+New DSW instances include default roles for the usual workflows:
+
+- **Researcher** for users who mainly create and work on their own projects.
+- **Data Steward** for users who prepare content such as knowledge models, document templates, and project templates.
+- **Admin** for users who manage the instance.
+
+The **Admin** role cannot be changed or deleted. Other default roles can be adjusted or deleted if they are not assigned to users and are not configured as the default role for new users.
+
+Custom Roles
+============
+
+Users with permission to manage settings can create custom roles when the default roles do not match the way an organization works. A role has a name and selected permissions.
+
+Custom roles are useful for cases such as:
+
+- a data support role that can view or comment on all projects
+- a user-management role that can manage users without managing settings
+- a content-management role that can work with knowledge models or document templates
+
+.. TODO::
+
+    Add a screenshot of the roles list showing default roles, custom roles, and the number of users assigned to each role.
+
+Role Permissions
+================
+
+Permissions are grouped by the type of work they enable.
+
+The role create/edit form includes these permissions:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Permission
+     - What it enables
+     - Implied permissions
+   * - **Manage Project Templates**
+     - Set projects as project templates. Users with this permission can also create new projects directly from knowledge models, even when project creation is restricted to templates.
+     - None.
+   * - **View ALL Projects**
+     - View all projects, regardless of project sharing and visibility settings.
+     - None.
+   * - **Comment on ALL Projects**
+     - Comment on all projects, regardless of project sharing and visibility settings.
+     - **View ALL Projects**
+   * - **Edit ALL Projects**
+     - Edit all projects, regardless of project sharing and visibility settings.
+     - **View ALL Projects**, **Comment on ALL Projects**
+   * - **Manage ALL Projects**
+     - Manage all projects as if the user were an owner, regardless of project sharing and visibility settings.
+     - **View ALL Projects**, **Comment on ALL Projects**, **Edit ALL Projects**
+   * - **Use Knowledge Model Editor**
+     - View, create, edit, and delete knowledge model editors, migrate them, and publish knowledge models from them.
+     - **Manage Knowledge Models**
+   * - **Manage Knowledge Models**
+     - Import, export, and delete knowledge models, set them as deprecated, restore them, or set them as public. This permission also allows users to manage knowledge model secrets.
+     - None.
+   * - **Use Document Template Editor**
+     - View, create, edit, and delete document template editors, and publish document templates from them.
+     - **Manage Document Templates**
+   * - **Manage Document Templates**
+     - Import, export, and delete document templates, and set them as deprecated or restore them.
+     - None.
+   * - **Manage Users**
+     - View, create, edit, and delete user accounts.
+     - None.
+   * - **Manage Settings**
+     - View and manage application settings.
+     - None.
+
+.. TODO::
+
+    Add a screenshot of the role create/edit form with permission groups and toggles visible.
+
+Global Roles and Project Sharing
+================================
+
+Global roles and :ref:`project sharing<sharing>` are related but separate.
+
+Project sharing controls access to a specific project. It is used for inviting collaborators as viewers, commenters, editors, or owners.
+
+Global role permissions can grant access across projects. For example, a role may allow a user to view, comment on, edit, or manage all projects in the instance. In that case, the user does not need to be listed explicitly in every project's sharing settings for that level of access.
+
+Project sharing is still used to manage collaboration inside a specific project, especially for project ownership and external/public access.
+
+Editing Roles
+=============
+
+When a role is changed, users assigned to that role receive the updated permissions. Before changing a role, check how many users are assigned to it.
+
+A role cannot be deleted if it is assigned to users. A role also cannot be deleted if it is configured as the :ref:`default role<authentication>` for new users.
+
+.. TODO::
+
+    Add a screenshot of a role detail page or edit form showing a role that cannot be deleted because it is assigned to users.