diff --git a/docs/about/introduction/knowledge-model.rst b/docs/about/introduction/knowledge-model.rst index c1eee85..865c8e1 100644 --- a/docs/about/introduction/knowledge-model.rst +++ b/docs/about/introduction/knowledge-model.rst @@ -82,7 +82,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: @@ -241,7 +241,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: diff --git a/docs/about/introduction/project.rst b/docs/about/introduction/project.rst index a30fbd4..fab239e 100644 --- a/docs/about/introduction/project.rst +++ b/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 →` diff --git a/docs/application/administration/index.rst b/docs/application/administration/index.rst index 6086039..afa0d16 100644 --- a/docs/application/administration/index.rst +++ b/docs/application/administration/index.rst @@ -3,7 +3,7 @@ Administration ************** -Administration section serves as the name suggests to users with permission to manage 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. ---- diff --git a/docs/application/administration/locales/create.rst b/docs/application/administration/locales/create.rst index cf52044..c2d1f8a 100644 --- a/docs/application/administration/locales/create.rst +++ b/docs/application/administration/locales/create.rst @@ -1,7 +1,7 @@ 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 `__, 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 `__, 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 `__-based) way. @@ -9,9 +9,8 @@ Similarly we can create a PO file for the emails. The needed POT files are placed in the localization repository `wizard-locales `__ (select the desired release and there is ``default.pot`` asset). -Recommended tool for creating the localization is the `Poedit `__. +Recommended tool for creating the localization is the `Poedit `__. .. figure:: create/form.png Form for creating a new locale. - diff --git a/docs/application/administration/locales/detail.rst b/docs/application/administration/locales/detail.rst index 804badb..f97ede4 100644 --- a/docs/application/administration/locales/detail.rst +++ b/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 `__, 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 `__, 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. diff --git a/docs/application/administration/locales/import.rst b/docs/application/administration/locales/import.rst index 30afc86..c5f8aba 100644 --- a/docs/application/administration/locales/import.rst +++ b/docs/application/administration/locales/import.rst @@ -11,7 +11,7 @@ We can import an existing locale by navigating to :menuselection:`Settings → L From DSW Registry ================= -If the |project_name| instance is connected to the `DSW Registry `__, 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 `__, 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,7 +28,7 @@ If the |project_name| instance is connected to the `DSW Registry `__ and service for translating using web browser `localize.ds-wizard.org `__. + We support community of DSW translators by managing the repository `ds-wizard/wizard-locales `__ and service for translating using web browser `localize.ds-wizard.org `__. .. figure:: index/list.png @@ -39,4 +39,4 @@ If there is a locale with newer version available in the `DSW Registry Create - Detail \ No newline at end of file + Detail diff --git a/docs/application/administration/roles/index.rst b/docs/application/administration/roles/index.rst index d306579..6d4fc36 100644 --- a/docs/application/administration/roles/index.rst +++ b/docs/application/administration/roles/index.rst @@ -3,12 +3,12 @@ Roles ***** -Roles define what users can do across the |project_name| 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. +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 |project_name| instances include default roles for the usual workflows: +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. @@ -35,7 +35,7 @@ Custom roles are useful for cases such as: Role Permissions ================ -Permissions are grouped by the type of work they enable. The available groups depend on the |project_name| edition and enabled features. +Permissions are grouped by the type of work they enable. The available groups depend on the DSW edition and enabled features. Project-related permissions can allow a role to: diff --git a/docs/application/administration/settings/content/dsw-registry.rst b/docs/application/administration/settings/content/dsw-registry.rst index 6bcec65..db5fb4e 100644 --- a/docs/application/administration/settings/content/dsw-registry.rst +++ b/docs/application/administration/settings/content/dsw-registry.rst @@ -3,11 +3,11 @@ DSW Registry ************ -In this settings, we can configure a connection to DSW Registry that will allow import of various content (Knowledge Models, Document Templates, and Locales) to our |project_name| instance. +In these settings, we can configure a connection to DSW Registry that will allow importing various content (Knowledge Models, Document Templates, and Locales) to our DSW instance. -Upon enabling the DSW Registry option, we are prompted to enter a **Token**. It can be obtained either by direct registration in the `DSW Registry__` or through clicking :guilabel:`Sign up` button. After clicking the button, we will need to enter details about organization (it is prefilled from :doc:`../system/organization`) and email address to which the confirmation will be sent (prefilled by email of the current user). Then, after clicking a link in the confirmation email, the token will be prefilled automatically. After having the token filled in either way, we can :guilabel:`Save` the settings. +Upon enabling the DSW Registry option, we are prompted to enter a **Token**. It can be obtained either by direct registration in the `DSW Registry `__ or by clicking the :guilabel:`Sign up` button. After clicking the button, we will need to enter details about the organization (prefilled from :doc:`../system/organization`) and the email address to which the confirmation will be sent (prefilled with the email of the current user). Then, after clicking a link in the confirmation email, the token will be prefilled automatically. After the token has been filled in either way, we can :guilabel:`Save` the settings. -After successfully setting the DSW Registry, we will see option to import from it for :ref:`Knowledge Models`, :ref:`Document Templates`, and :ref:`Locales`. +After successfully setting the DSW Registry, we will see the option to import from it for :ref:`Knowledge Models`, :ref:`Document Templates`, and :ref:`Locales`. .. NOTE:: diff --git a/docs/application/administration/settings/content/projects.rst b/docs/application/administration/settings/content/projects.rst index 2a706ae..91fb4fc 100644 --- a/docs/application/administration/settings/content/projects.rst +++ b/docs/application/administration/settings/content/projects.rst @@ -4,7 +4,7 @@ Projects Project Visibility ================== -If we want to let users select visibility of their projects within the |project_name| instance, we can enable **Project Visibility** feature. If it is disabled, the new projects will have the **Default Project Visibility** which is used when creating a new project: +If we want to let users select visibility of their projects within the DSW instance, we can enable **Project Visibility** feature. If it is disabled, the new projects will have the **Default Project Visibility** which is used when creating a new project: * **Private** = the project is visible only to the users with explicit access to the project. * **Visible - View** = the project is visible in view-only mode to all logged-in users, i.e. all users will be able to see the project in their :ref:`projects list` and access it (but not edit or comment anything unless they are invited with different permissions). @@ -19,7 +19,7 @@ If we want to let users select visibility of their projects within the |project_ Project Sharing =============== -If we want to let users select sharing option of their projects within the |project_name| instance, we can enable **Project Sharing** feature. If it is disabled, the new projects will have the **Default Project Sharing** which is used when creating a new project: +If we want to let users select sharing options for their projects within the DSW instance, we can enable the **Project Sharing** feature. If it is disabled, the new projects will have the **Default Project Sharing** which is used when creating a new project: * **Restricted** = only logged-in users can access the project depending on the project visibility (no public access for anonymous users). * **View with the link** = anyone with the link to the project may open it in view mode and browse it. @@ -34,7 +34,7 @@ If we want to let users select sharing option of their projects within the |proj Anonymous Projects ================== -If we have set Knowledge Model as Public, we can also allow anonymous users to create projects where they will be able to fill questionnaires by enabling **Anonymous Projects**. These anonymous project then work as any other projects with public link set to edit permissions. However, if a logged-in user accesses such a project, then such a user may claim the ownership by clicking :guilabel:`Add to my projects` button. Anonymous users cannot create new documents, for that they must register and open the project as a logged-in user. +If we have set Knowledge Model as Public, we can also allow anonymous users to create projects where they will be able to fill questionnaires by enabling **Anonymous Projects**. These anonymous projects then work as any other projects with public link set to edit permissions. However, if a logged-in user accesses such a project, then they may claim the ownership by clicking the :guilabel:`Add to my projects` button. Anonymous users cannot create new documents; for that, they must register and open the project as a logged-in user. Project Creation @@ -42,7 +42,7 @@ Project Creation * **Templates & Custom** = users can create both projects from project templates and custom projects. * **Templates Only** = users can create projects only from project templates. -* **Custom Only** = users can create only custom projects, they have to select knowledge model and everything else by themselves. +* **Custom Only** = users can create only custom projects, they have to select a knowledge model and everything else by themselves. Summary Report @@ -56,4 +56,4 @@ The **Summary Report** shows how many questions are answered and unanswered in e Project Tagging =============== -If enabled, users will be able to tag their projects (using so-called **Project Tags**) and then use those tags to filter the :ref:`projects list`. The users will be always able to write their own tags but we can provide a list of pre-defined **Default Project Tags** (one per line). +If enabled, users will be able to tag their projects (using so-called **Project Tags**) and then use those tags to filter the :ref:`projects list`. The users will always be able to write their own tags, but we can provide a list of pre-defined **Default Project Tags** (one per line). diff --git a/docs/application/administration/settings/info/index.rst b/docs/application/administration/settings/info/index.rst index 7d484c0..7e8f29d 100644 --- a/docs/application/administration/settings/info/index.rst +++ b/docs/application/administration/settings/info/index.rst @@ -1,7 +1,7 @@ Info **** -The info section of settings simply serves to let us check various information and statistics about the |project_name| instance. +The info section of settings simply serves to let us check various information and statistics about the DSW instance. ---- diff --git a/docs/application/administration/settings/info/usage.rst b/docs/application/administration/settings/info/usage.rst index 31cff30..567257a 100644 --- a/docs/application/administration/settings/info/usage.rst +++ b/docs/application/administration/settings/info/usage.rst @@ -1,7 +1,7 @@ Usage ***** -Usage allows us quickly see numbers of entities in the |project_name| instance such as number of users, active users, knowledge models, KM editors, templates, projects, or documents. Moreover, we can see storage usage, i.e. how much capacity is being used by documents and templates (their files). We cannot perform any actions on this page. +Usage allows us quickly see numbers of entities in the DSW instance such as number of users, active users, knowledge models, KM editors, templates, projects, or documents. Moreover, we can see storage usage, i.e. how much capacity is being used by documents and templates (their files). We cannot perform any actions on this page. .. figure:: usage/usage.png diff --git a/docs/application/administration/settings/system/authentication.rst b/docs/application/administration/settings/system/authentication.rst index cf73af6..4dbf74d 100644 --- a/docs/application/administration/settings/system/authentication.rst +++ b/docs/application/administration/settings/system/authentication.rst @@ -8,7 +8,7 @@ The **Default Role** settings option allows us to define which :ref:`role .. WARNING:: - It is recommended to set this to the lowest-privilege role that fits new users. Otherwise, new users may be able to change content or settings for other users in the |project_name| instance. + It is recommended to set this to the lowest-privilege role that fits new users. Otherwise, new users may be able to change content or settings for other users in the DSW instance. .. NOTE:: @@ -21,7 +21,7 @@ Internal For internal authentication, we can set: - **Registration** - whether users can sign up on their own or not. -- **Non-Admin Login** - whether non-admin users can log in to the |project_name| instance or not. +- **Non-Admin Login** - whether non-admin users can log in to the DSW instance or not. - **Two-Factor Authentication** - whether users need to confirm their login with a one-time code sent to their email address or not. - **Session Expiration** - how long the user session is valid before the user needs to log in again in hours. - **User Email Link Expiration** - how long the email links (e.g., for password reset) are valid before they expire and cannot be used anymore in hours. diff --git a/docs/application/administration/settings/system/authentication/openid.png b/docs/application/administration/settings/system/authentication/openid.png deleted file mode 100644 index 13a0a5e..0000000 Binary files a/docs/application/administration/settings/system/authentication/openid.png and /dev/null differ diff --git a/docs/application/administration/settings/system/index.rst b/docs/application/administration/settings/system/index.rst index a20193e..1395fba 100644 --- a/docs/application/administration/settings/system/index.rst +++ b/docs/application/administration/settings/system/index.rst @@ -1,7 +1,7 @@ System ****** -System settings allow us to configure basics about the organization running the |project_name| instance, how can user register and login, and finally the privacy and support information for the users. +System settings allow us to configure basics about the organization running the DSW instance, how can user register and login, and finally the privacy and support information for the users. ---- diff --git a/docs/application/administration/settings/system/openid.rst b/docs/application/administration/settings/system/openid.rst index 5d17b51..bfdf200 100644 --- a/docs/application/administration/settings/system/openid.rst +++ b/docs/application/administration/settings/system/openid.rst @@ -3,9 +3,9 @@ OpenID ****** -Using these settings we can add `OpenID `__ configuration to allow logging into the DSW via external identity provider. +Using these settings, we can add `OpenID `__ configuration to allow logging into DSW via an external identity provider. -DSW supports Microsoft Azure, ORCID, as well as any other OpenID providers. Following are detailed description of the setups for these options. +DSW supports Microsoft Azure, ORCID, and other OpenID providers. The following sections describe the setup for these options. .. NOTE:: @@ -26,18 +26,18 @@ Microsoft Azure Setup 9. Click on ``Manage`` in the left menu → ``Certificates & Secrets``. 10. Click on ``New client secret``. 11. Fill description, set ``Expires`` and note it somewhere, then click on ``Add``. -12. Copy ``Value`` and store it somewhere. You will not able to view it again. +12. Copy ``Value`` and store it somewhere. You will not be able to view it again. 13. Go to OpenID in DSW: ``Settings`` → ``OpenID`` → ``Create``. 14. Fill in a ``Name`` of the service. This name will be used to identify the service in the list of login options, so it should be something descriptive. -15. Open the ``Microsoft`` tab and fill in : +15. Open the ``Microsoft`` tab and fill in: - ``Application (client) ID`` - ``Directory (tenant) ID`` - ``Client Secret`` → ```` -16. (optional) fill Icon (``fab fa-microsoft``, or some other from `Font Awesome `_), ``Background Color`` and ``Text Color``. +16. (optional) Fill in Icon (``fab fa-microsoft``, or another icon from `Font Awesome `_), ``Background Color`` and ``Text Color``. 17. Click on ``Save``. @@ -59,12 +59,7 @@ Microsoft Azure Setup 32. Select ``ID`` and check ``email``, ``family_name`` and ``given_name``. 33. Click on ``Add``. -34. Test your OpenID configuration in DSW (You might need to refresh the login page for the login button to appear). - -.. .. figure:: openid/openid.png -.. :width: 700 - -.. Example configuration of OpenID Microsoft Azure service. +34. Test your OpenID configuration in DSW. You might need to refresh the login page for the login button to appear. ORCID Setup @@ -80,7 +75,7 @@ ORCID requires a redirect URI before it allows us to save the application and ob - ``Client Secret`` → ``placeholder`` - ``URL`` → ``https://orcid.org`` 5. Leave ``Parameters`` empty. -6. (optional) fill Icon (``fab fa-orcid``), ``Background Color`` (``#A6CE39``), and ``Text Color``. +6. (optional) Fill in Icon (``fab fa-orcid``), ``Background Color`` (``#A6CE39``), and ``Text Color``. 7. Click on ``Save``. 8. Copy ``Callback URL`` from DSW. It will look similar to ``https:///wizard/open-id//callback``. @@ -101,7 +96,7 @@ ORCID requires a redirect URI before it allows us to save the application and ob - ``Client Secret`` → ORCID ``Client Secret`` - ``URL`` → keep ``https://orcid.org`` 17. Click on ``Save``. -18. Test your OpenID configuration in DSW (You might need to refresh the login page for the login button to appear). +18. Test your OpenID configuration in DSW. You might need to refresh the login page for the login button to appear. .. NOTE:: @@ -131,9 +126,9 @@ Custom Setup - Configure the client to provide the following details in ID tokens: ``email``, ``given_name``, ``family_name``. 8. Go back to DSW and fill in the real ``Client ID``, ``Client Secret``, and ``URL`` from the OpenID provider. 9. Leave ``Parameters`` empty unless the provider documentation requires an additional parameter. -10. (optional) fill Icon (some from `Font Awesome `_), ``Background Color`` and ``Text Color``. +10. (optional) Fill in Icon (an icon from `Font Awesome `_), ``Background Color`` and ``Text Color``. 11. Click on ``Save``. -12. Test your OpenID configuration in DSW (You might need to refresh the login page for the login button to appear). +12. Test your OpenID configuration in DSW. You might need to refresh the login page for the login button to appear. Advanced Configuration diff --git a/docs/application/administration/settings/system/organization.rst b/docs/application/administration/settings/system/organization.rst index 830638b..b163a3c 100644 --- a/docs/application/administration/settings/system/organization.rst +++ b/docs/application/administration/settings/system/organization.rst @@ -3,7 +3,7 @@ Organization ************ -On this page, we can configure **Name**, **Description**, **Organization ID** for our |project_name| instance and **Affiliations**. +On this page, we can configure **Name**, **Description**, **Organization ID** for our DSW instance and **Affiliations**. The organization ID is used as a part of knowledge models and document templates IDs. That ID is also used in the :ref:`dsw-registry` to identify the organization. diff --git a/docs/application/administration/settings/user-interface/dashboard-and-login-screen.rst b/docs/application/administration/settings/user-interface/dashboard-and-login-screen.rst index 2b31e01..811f7b7 100644 --- a/docs/application/administration/settings/user-interface/dashboard-and-login-screen.rst +++ b/docs/application/administration/settings/user-interface/dashboard-and-login-screen.rst @@ -30,7 +30,7 @@ We can select the **Dashboard Style** to decide whether the user should see a st * **Configure Organization Widget** quickly navigates to :doc:`../system/organization` if it is not yet done. - * **Configure Look and Feel Widget** quickly navigates to :doc:`../user-interface/look-and-feel` to adjust style of the |project_name| instance. + * **Configure Look and Feel Widget** quickly navigates to :doc:`../user-interface/look-and-feel` to adjust style of the DSW instance. * **Connect DSW Registry Widget** quickly navigates to :doc:`../content/dsw-registry` to configure the connection if it has not been configured yet. @@ -42,11 +42,11 @@ We can select the **Dashboard Style** to decide whether the user should see a st Login Info ========== -It is possible to write a message that users will see before logging in the |project_name| instance, using HTML or Markdown. The Login info is placed in the center of the login screen. We can use it to explain users in what cases they can/should use our |project_name| instance, how they should log in (e.g. if we have more authentication services configured), or if there is any news regarding our |project_name| instance. +It is possible to write a message that users will see before logging in the DSW instance, using HTML or Markdown. The Login info is placed in the center of the login screen. We can use it to explain users in what cases they can/should use our DSW instance, how they should log in (e.g. if we have more authentication services configured), or if there is any news regarding our DSW instance. .. WARNING:: - Defining HTML classes in the login info can overwrite |project_name| application classes. It is recommended to use prefixes for classes, if they are used, to avoid conflicts. + Defining HTML classes in the login info can overwrite DSW application classes. It is recommended to use prefixes for classes, if they are used, to avoid conflicts. .. _sidebar-login-info: diff --git a/docs/application/administration/settings/user-interface/index.rst b/docs/application/administration/settings/user-interface/index.rst index ca09eb7..8a6e5d4 100644 --- a/docs/application/administration/settings/user-interface/index.rst +++ b/docs/application/administration/settings/user-interface/index.rst @@ -1,7 +1,7 @@ User Interface Settings *********************** -User Interface (UI) settings allow us to manage how the |project_name| instance looks like: styling, titles, or the dashboard shown when user logs information. +User Interface (UI) settings allow us to manage how the DSW instance looks like: styling, titles, or the dashboard shown when user logs information. ---- diff --git a/docs/application/administration/settings/user-interface/look-and-feel.rst b/docs/application/administration/settings/user-interface/look-and-feel.rst index d8cfd63..b53d616 100644 --- a/docs/application/administration/settings/user-interface/look-and-feel.rst +++ b/docs/application/administration/settings/user-interface/look-and-feel.rst @@ -1,22 +1,21 @@ Look & Feel *********** -This part of settings allows us to adjust how the |project_name| instance looks like. +This part of settings allows us to adjust how the DSW instance looks like. Application Titles ================== -There are two titles that we can set. First, **Application Title** is the full title that should identify the |project_name| instance, for example, in browser's tab. Second is **Short Application Title** which is visible, for example, at the top of the main (left) menu next to the icon. We should keep **Short Application Title** really short (about 10 characters at maximum) so it fits well. +There are two titles that we can set. First, **Application Title** is the full title that should identify the DSW instance, for example, in browser's tab. Second is **Short Application Title** which is visible, for example, at the top of the main (left) menu next to the icon. We should keep **Short Application Title** really short (about 10 characters at maximum) so it fits well. Custom Menu Links ================= -We can easily add custom links to the main (left) menu by clicking :guilabel:`Add` under **Custom Menu Links**. For each link, we can set **Icon** (from `Font Awesome `_), **Title** and the target **URL**. We can also set whether the link should open in **New Window** (if not, it will navigate user directly in the same window/tab from |project_name| instance). Once the links are there, we can manage them or delete them at this place. +We can easily add custom links to the main (left) menu by clicking :guilabel:`Add` under **Custom Menu Links**. For each link, we can set **Icon** (from `Font Awesome `_), **Title** and the target **URL**. We can also set whether the link should open in **New Window** (if not, it will navigate user directly in the same window/tab from DSW instance). Once the links are there, we can manage them or delete them at this place. .. figure:: look-and-feel/custom-links.png - + Example configuration of a custom menu link. - \ No newline at end of file diff --git a/docs/application/administration/users/detail.rst b/docs/application/administration/users/detail.rst index 8c9f77a..797440a 100644 --- a/docs/application/administration/users/detail.rst +++ b/docs/application/administration/users/detail.rst @@ -10,7 +10,7 @@ Users with permission to manage users can edit existing users manually on the de Detail of a user profile. -The password can be also changed (after selecting :guilabel:`Password` from the left navigation of user settings). +The password can also be changed (after selecting :guilabel:`Password` from the left navigation of user settings). .. figure:: detail/password.png @@ -21,7 +21,7 @@ The password can be also changed (after selecting :guilabel:`Password` from the User Roles ========== -Each user has one global :ref:`role`. The role determines which parts of the |project_name| instance the user can access and what actions they can perform. +Each user has one global :ref:`role`. The role determines which parts of the DSW instance the user can access and what actions they can perform. Default roles cover the common researcher, data steward, and admin workflows. Users with permission to manage settings can also create custom roles when they need a different combination of permissions. diff --git a/docs/application/administration/users/index.rst b/docs/application/administration/users/index.rst index 8ee75bc..e4d85b4 100644 --- a/docs/application/administration/users/index.rst +++ b/docs/application/administration/users/index.rst @@ -3,9 +3,9 @@ Users ***** -Users list allows users with permission to manage users to see and manage all users in a |project_name| instance. The list can be filtered using :ref:`roles`, searched based using name or email fragment, and sorted via various properties of users. The list shows the role of a user next to its name and also indicates in case the user is inactive. Next to the email, we can quickly see what authentication services the user uses to log-in. +A users list allows users with permission to manage users to see and manage all users in a DSW instance. The list can be filtered using :ref:`roles`, searched by name or email fragment, and sorted via various user properties. The list shows the role of a user next to their name and also indicates when the user is inactive. Next to the email, we can quickly see what authentication services the user uses to log in. -A :ref:`user detail` can be opened by clicking the name of a user or by selecting :guilabel:`Edit` in the right dropdown menu for the desired row. There, a user can be also deleted via the :guilabel:`Delete` action. Finally, a new user can be :ref:`created` by clicking :guilabel:`Create`. +A :ref:`user detail` can be opened by clicking the name of a user or by selecting :guilabel:`Edit` in the right dropdown menu for the desired row. There, a user can also be deleted via the :guilabel:`Delete` action. Finally, a new user can be :ref:`created` by clicking :guilabel:`Create`. .. figure:: index/list.png diff --git a/docs/application/document-templates/editors/index.rst b/docs/application/document-templates/editors/index.rst index 5e19900..d2e6db1 100644 --- a/docs/application/document-templates/editors/index.rst +++ b/docs/application/document-templates/editors/index.rst @@ -14,7 +14,7 @@ We can use the search field to search for a specific document template editor. T We can :doc:`./create` by clicking the :guilabel:`Create` button. -By clicking the triple dots on each of the item in the list we can access some actions: +By clicking the triple dots on each item in the list, we can access some actions: - **Open Editor** - simply open the :doc:`./detail/index` (we can also click the name of the editor) - **Delete** - to delete the document template editor (cannot be undone) diff --git a/docs/application/document-templates/list/import.rst b/docs/application/document-templates/list/import.rst index ce1fbff..8a31820 100644 --- a/docs/application/document-templates/list/import.rst +++ b/docs/application/document-templates/list/import.rst @@ -10,7 +10,7 @@ We can import an existing document template by navigating to :doc:`./index` (:me From DSW Registry ================= -If the |project_name| instance is connected to the `DSW Registry `__, it is possible to import document templates from it by entering the **document template ID** of desired template (e.g. ``dsw:questionnaire-report:2.7.1``) and pressing the :guilabel:`Import` button. +If the DSW instance is connected to the `DSW Registry `__, it is possible to import document templates from it by entering the **document template ID** of desired template (e.g. ``dsw:questionnaire-report:2.7.1``) and pressing the :guilabel:`Import` button. .. NOTE:: @@ -26,7 +26,7 @@ If the |project_name| instance is connected to the `DSW Registry `__, :guilabel:`update available` badge will appear. +Each item may be marked with :guilabel:`unsupported metamodel` badge when the document template is not compatible with the version of DSW. :doc:`../../../more/development/metamodel-schemas` are used to define structures that developers can interact with. If the template originates from the `DSW Registry `__, :guilabel:`update available` badge will appear. To see how to configure the registry, read the :ref:`FAQ and Deployment Notes`. If your template is not from the registry, you will have to :doc:`../editors/detail/publish` a new version via template editor, which will increase the metamodel version automatically. diff --git a/docs/application/knowledge-models/editors/create.rst b/docs/application/knowledge-models/editors/create.rst index e9d3e08..b069cfe 100644 --- a/docs/application/knowledge-models/editors/create.rst +++ b/docs/application/knowledge-models/editors/create.rst @@ -17,6 +17,6 @@ Every knowledge model needs to have a **name**, a **knowledge model ID** and **v :: -We can create a new project either from scratch, i.e. the new knowledge model will be empty and we will build it all ourselves, or based on an existing knowledge models, which means that everything from the chosen knowledge model will be copied to ours. We can start from there and add, delete, or modify the existing entities in there. We just need to choose the original knowledge model in the **based on** field. Alternatively, we can open the :ref:`knowledge model detail` and click on :guilabel:`Fork KM` there. +We can create a new knowledge model editor either from scratch, i.e. the new knowledge model will be empty and we will build it all ourselves, or based on an existing knowledge model, which means that everything from the chosen knowledge model will be copied to ours. We can start from there and add, delete, or modify the existing entities in there. We just need to choose the original knowledge model in the **Based on** field. Alternatively, we can open the :ref:`knowledge model detail` and click on :guilabel:`Fork KM` there. We can only have one knowledge model editor with the same knowledge model ID. If we deleted the editor but want to continue working on that knowledge model, we can create a new editor with the same knowledge model ID. Or we can open the :ref:`knowledge model detail` and click on :guilabel:`Create KM editor` there to have the editor create form prefilled. diff --git a/docs/application/knowledge-models/editors/index.rst b/docs/application/knowledge-models/editors/index.rst index baed544..77958dc 100644 --- a/docs/application/knowledge-models/editors/index.rst +++ b/docs/application/knowledge-models/editors/index.rst @@ -10,14 +10,14 @@ Users with permission to use knowledge model editors can see a list of all knowl List of knowledge model editors. -We can use the search field to search for a specific KM editor. The editors are sorted by when they were last updated but we can change that. We can order the list by name, creation date, or last update date. The list shows the name, version, id, if editor contains unpublished changes, if it is a fork of different KM and last update. +We can use the search field to search for a specific KM editor. The editors are sorted by when they were last updated, but we can change that. We can order the list by name, creation date, or last update date. The list shows the name, version, id, whether the editor contains unpublished changes, whether it is a fork of a different KM, and last update. We can :ref:`create a new knowledge model editor` by clicking the :guilabel:`Create` button. -By clicking the triple dots on each of the item in the list we can access some actions: +By clicking the triple dots on each item in the list, we can access some actions: - **Open Editor** - simply open the :ref:`editor detail` -- **Update** - if there is a newer version of parent knowledge model, we can use update action to start a :ref:`knowledge model migration`, otherwise the action is not visible +- **Update** - if there is a newer version of the parent knowledge model, we can use the update action to start a :ref:`knowledge model migration`, otherwise the action is not visible - **Delete** - to delete the knowledge model editor (cannot be undone) If there is an ongoing :ref:`knowledge model migration`, there are different actions: diff --git a/docs/application/knowledge-models/list/import.rst b/docs/application/knowledge-models/list/import.rst index 1e95a3b..0166bf6 100644 --- a/docs/application/knowledge-models/list/import.rst +++ b/docs/application/knowledge-models/list/import.rst @@ -27,7 +27,7 @@ We can import a knowledge model from the `DSW Registry ` can be used to quickly submit the document directly from |project_name| to some external service. +:ref:`Submission services` can be used to quickly submit the document directly from DSW to some external service. .. figure:: documents/submission.png :width: 540 @@ -39,6 +39,6 @@ Document Submission Submission service selection for a document. -If there are any document submission services configured for our |project_name| instance, we should be able to see :guilabel:`Submit` option when we open document menu in the document list by clicking on the triple dots. Then we choose the desired from the list and click on :guilabel:`Submit`. +If there are any document submission services configured for our DSW instance, we should be able to see :guilabel:`Submit` option when we open document menu in the document list by clicking on the triple dots. Then we choose the desired from the list and click on :guilabel:`Submit`. We can see all the submissions for each document in the document list as well. \ No newline at end of file diff --git a/docs/application/projects/list/detail/settings.rst b/docs/application/projects/list/detail/settings.rst index 1b7d88e..2e8b3b3 100644 --- a/docs/application/projects/list/detail/settings.rst +++ b/docs/application/projects/list/detail/settings.rst @@ -5,11 +5,11 @@ Settings In the :guilabel:`Settings` tab, we can configure some details about the project. First we have a **name** and a **description** to identify the project. -Next, we have **Project Tags**. These can be used for providing some metadata or categorization of the project. In the project list, we can filter the projects by these tags. We can write any text we want as a project tag and |project_name| will suggest us the tags that are there already in use so we can keep them consistent. +Next, we have **Project Tags**. These can be used for providing some metadata or categorization of the project. In the project list, we can filter the projects by these tags. We can write any text we want as a project tag and DSW will suggest us the tags that are there already in use so we can keep them consistent. .. NOTE:: - Project tags might be disabled in some |project_name| instances. + Project tags might be disabled in some DSW instances. .. figure:: settings/settings.png @@ -35,7 +35,7 @@ We can use the project as a :ref:`project template`. If we en Project template options are visible only for users with permission to manage project templates. -:guilabel:`Unsupported metamodel` badge can appear, when the document template is not compatible with the version of |project_name|. Users should contact the person responsible for document templates or instance administration in this case. +:guilabel:`Unsupported metamodel` badge can appear, when the document template is not compatible with the version of DSW. Users should contact the person responsible for document templates or instance administration in this case. Knowledge Model =============== diff --git a/docs/application/projects/list/detail/sharing.rst b/docs/application/projects/list/detail/sharing.rst index 9b5a4c7..bcf8836 100644 --- a/docs/application/projects/list/detail/sharing.rst +++ b/docs/application/projects/list/detail/sharing.rst @@ -3,7 +3,7 @@ Sharing ******* -We can share a project with other |project_name| users or external collaborators. We can access all sharing options by clicking the :guilabel:`Share` button in the top right. +We can share a project with other DSW users or external collaborators. We can access all sharing options by clicking the :guilabel:`Share` button in the top right. .. figure:: sharing/share-modal.png :width: 540 @@ -141,7 +141,7 @@ There are different project sharing roles that grant access to different project .. NOTE:: - Some of the following options might be globally disabled in the application settings for the whole |project_name| instance, therefore not visible on the project level. + Some of the following options might be globally disabled in the application settings for the whole DSW instance, therefore not visible on the project level. The following video tutorial explains and showcases sharing options and tools that can be used while collaborating with others. Some features mentioned in the video are also explained in the :ref:`project questionnaire`. @@ -154,7 +154,7 @@ The following video tutorial explains and showcases sharing options and tools th Users ===== -We can choose specific users from the |project_name| instance and their project sharing role to grant them access to project features based on the table above. This is a good way to add other collaborators that work together with us on the project. Also, this is the only way to add other project owners. +We can choose specific users from the DSW instance and their project sharing role to grant them access to project features based on the table above. This is a good way to add other collaborators that work together with us on the project. Also, this is the only way to add other project owners. Visible by all other logged-in users @@ -168,4 +168,4 @@ This can be useful, when we want to have an example project accessible by everyb Public link =========== -We can enable the :guilabel:`Public link` toggle to grant access to the project to anyone who has the link. We can again choose what they can do -- **view**, **comment**, or **edit** the project. Also, the public link is visible there, so we can simply copy it and send to whoever we want to collaborate with. Then, they don't need a |project_name| account and still be able to access our project. +We can enable the :guilabel:`Public link` toggle to grant access to the project to anyone who has the link. We can again choose what they can do -- **view**, **comment**, or **edit** the project. Also, the public link is visible there, so we can simply copy it and send to whoever we want to collaborate with. Then, they don't need a DSW account and still be able to access our project. diff --git a/docs/application/projects/list/index.rst b/docs/application/projects/list/index.rst index 79427cc..77cec9d 100644 --- a/docs/application/projects/list/index.rst +++ b/docs/application/projects/list/index.rst @@ -3,11 +3,11 @@ Project List ************ -In the project list, we can see a list of all projects we have access to. Those are the projects where we were assigned with a project sharing role, projects that are visible to all logged-in users in the :ref:`project sharing settings`, or projects available through our global :ref:`role` permissions. The projects are filtered to those we are explicitly assigned to by default. +In the project list, we can see a list of all projects we have access to. Those are the projects where we were assigned a project sharing role, projects that are visible to all logged-in users in the :ref:`project sharing settings`, or projects available through our global :ref:`role` permissions. The projects are filtered to those we are explicitly assigned to by default. -We can see projects name, label :guilabel:`Template` if the project is a template, and icon indicating sharing settings: +We can see project names, a :guilabel:`Template` label if the project is a template, and an icon indicating sharing settings: -- **Lock icon** - the project can be only accessed by you +- **Lock icon** - the project can only be accessed by you - **People icon** - the project is shared with other users, hovering on the icon provides additional information - **Globe icon** - anyone with a link can access the project @@ -19,18 +19,18 @@ We can see projects name, label :guilabel:`Template` if the project is a templat We can search for specific projects using the search field or filter them using additional filters: - **Project Template** - if we want to see only :ref:`project templates` or regular projects -- **Project Tags** - show only the projects that has specific tags assigned +- **Project Tags** - show only the projects that have specific tags assigned - **Knowledge Models** - show only the projects created from a specific knowledge model - **Users** - filter only the projects with specific users assigned to them .. NOTE:: - Note that some of the filters can be disabled based on the |project_name| instance settings or user permissions. + Note that some of the filters can be disabled based on the DSW instance settings or user permissions. We can :ref:`create a new project` by clicking the :guilabel:`Create` button. -By clicking the triple dots on each of the item in the list we can access some actions: +By clicking the triple dots on each item in the list, we can access some actions: - **Open project** - will simply open the project - **Create project from this template** - will create a new project from the selected project template (this is only available if the project is also a project template) diff --git a/docs/application/projects/list/templates.rst b/docs/application/projects/list/templates.rst index 5622c27..5401d41 100644 --- a/docs/application/projects/list/templates.rst +++ b/docs/application/projects/list/templates.rst @@ -9,9 +9,9 @@ Project Templates When creating a new project, we need to choose a knowledge model and optionally select some question tags. After the project is created, we should also choose a :ref:`default document template` and format to enable :ref:`preview`. It can be overwhelming for new researchers to set up everything when they are new to all this. -Project templates are special type of projects where we can set up everything -- choose a knowledge model and question tags, set up default document template, pre-fill some answers, add TODOs, comments or editor notes. Users can then pick from these project templates when :ref:`creating a new project`. The new project will be the exact copy of the project template so they don't have to set those things themselves and they have an easier start to their data management planning. +Project templates are a special type of project where we can set up everything -- choose a knowledge model and question tags, set up a default document template, pre-fill some answers, add TODOs, comments or editor notes. Users can then pick from these project templates when :ref:`creating a new project`. The new project will be an exact copy of the project template, so they don't have to set those things themselves and they have an easier start to their data management planning. -When we want to turn a project into a project template we need to go to the :ref:`project settings` and check the :guilabel:`Project Template` checkbox. +When we want to turn a project into a project template, we need to go to the :ref:`project settings` and check the :guilabel:`Project Template` checkbox. Sharing the Project Templates ============================= @@ -20,7 +20,7 @@ Sharing the Project Templates Project templates follow the same rules for sharing as regular projects. Therefore, to make it available for other users, we need to set up proper :ref:`sharing settings`. -We can either share them with specific users only, or we can simply enable that the project template is **visible by all other logged-in users** and that they can only **view** it (as we do not want them to change it). +We can either share them with specific users only, or we can simply make the project template **visible by all other logged-in users** with **view** access only (as we do not want them to change it). External Resources diff --git a/docs/conf.py b/docs/conf.py index d067fa8..0f3dda2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,20 +21,9 @@ copyright = '2018 - 2026, DSW Team' author = 'DSW Team' -project_name = 'DSW' -project_name_full = 'Data Stewardship Wizard' - # The full version, including alpha/beta/rc tags version = release = '4.32' -rst_prolog = f""" - -.. |compose_ver| replace:: {release} -.. |project_name| replace:: {project_name} -.. |project_name_full| replace:: {project_name_full} - -""" - # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be @@ -97,6 +86,11 @@ def setup(app): 'epub.unknown_project_files', ] +linkcheck_ignore = [ + r'http://localhost(:\d+)?(/.*)?$', + r'https://localhost(:\d+)?(/.*)?$', +] + redirects = { 'more/roadmap/index': 'https://changelog.ds-wizard.org', diff --git a/docs/index.rst b/docs/index.rst index 198c5dc..6aa604a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,15 +1,15 @@ -|project_name| User Guide +DSW User Guide ************************* -The |project_name_full| is a tool that helps researchers and data stewards create data management plans (DMPs) easily, efficiently, and in a FAIR manner. +The Data Stewardship Wizard is a tool that helps researchers and data stewards create data management plans (DMPs) easily, efficiently, and in a FAIR manner. Data stewards can easily capture the knowledge, including required project data and decisions in knowledge models that are then turned into per-project questionnaires to be filled by researchers. The questionnaires guide researchers through the process using recommendations, FAIR metrics indications, and only showing relevant questions based on previous answers. -Once the questionnaire is completed, a DMP can be easily generated using a selected template and output format. The document is then stored in |project_name| for easy access and future reference. This is especially helpful because many funding agencies now require a DMP for their application process. +Once the questionnaire is completed, a DMP can be easily generated using a selected template and output format. The document is then stored in DSW for easy access and future reference. This is especially helpful because many funding agencies now require a DMP for their application process. -But the benefits of using |project_name| go beyond just creating a DMP. Researchers also learn how to handle data correctly, make it FAIR, maintain it throughout the project, and curate it long-term. This intelligent, guided, and efficient approach to composing DMPs is useful for ELIXIR nodes, research institutions, and individual researchers alike. +But the benefits of using DSW go beyond just creating a DMP. Researchers also learn how to handle data correctly, make it FAIR, maintain it throughout the project, and curate it long-term. This intelligent, guided, and efficient approach to composing DMPs is useful for ELIXIR nodes, research institutions, and individual researchers alike. -You are welcome to join the `Discord community `__ where you can ask questions, share your experience, and get help from other users and administrators of |project_name|. +You are welcome to join the `Discord community `__ where you can ask questions, share your experience, and get help from other users and administrators of DSW. .. youtube:: gcSPG_dyVUQ :width: 100% @@ -22,8 +22,8 @@ Structure of the Guide The guide sections are organized into three categories: - **About** contains an introduction to the Data Stewardship Wizard and its content to gain quick insight into how it works at a high level. -- **Application** is structured the same way as |project_name|'s main menu to quickly find the relevant sections about how to use a specific part of the application. -- **More** contains all additional information related to |project_name|, such as development roadmap, how to develop own content, or how to run own instance. +- **Application** is structured the same way as DSW's main menu to quickly find the relevant sections about how to use a specific part of the application. +- **More** contains all additional information related to DSW, such as development roadmap, how to develop own content, or how to run own instance. Here are some recommended sections where to start based on the role: diff --git a/docs/more/development/contributing.rst b/docs/more/development/contributing.rst index 9ef80c0..6351917 100644 --- a/docs/more/development/contributing.rst +++ b/docs/more/development/contributing.rst @@ -2,7 +2,7 @@ Contributing ************ -Interested in contributing to the |project_name| development? +Interested in contributing to the DSW development? ---- @@ -22,7 +22,7 @@ In case you find some bug, please `create an issue `__. However, never include sensitive information in the issue as it is publicly available. Such information (e.g. logs) send to us via e-mail `support@ds-wizard.org `__. +If you find an security issue within DSW, please `create appropriate issue `__. However, never include sensitive information in the issue as it is publicly available. Such information (e.g. logs) send to us via e-mail `support@ds-wizard.org `__. Development =========== @@ -42,9 +42,9 @@ Our projects are open source and you can contribute via GitHub (fork and pull re Test Policy =========== -Testing is essential to ensure the successful construction and implementation of |project_name|. It is necessary to keep tests updated together with new features and other changes in the code. +Testing is essential to ensure the successful construction and implementation of DSW. It is necessary to keep tests updated together with new features and other changes in the code. -Each component may use its own test suite (unit tests, acceptance tests, integration tests), which shall be described in the CONTRIBUTING file within the corresponding repository. To test all components together, we have the `E2E test suite `__ (Cypress) that tests according to various use cases, i.e., what can a user do within |project_name| using its web user interface. +Each component may use its own test suite (unit tests, acceptance tests, integration tests), which shall be described in the CONTRIBUTING file within the corresponding repository. To test all components together, we have the `E2E test suite `__ (Cypress) that tests according to various use cases, i.e., what can a user do within DSW using its web user interface. Whenever a new feature is developed, it must be covered by tests. For the E2E test suite, a specific sub-task is created in our JIRA when applicable. All components must pass all tests before releasing (including release candidate versions). diff --git a/docs/more/development/document-templates/dev-notes.rst b/docs/more/development/document-templates/dev-notes.rst index 62fcd3f..d39cd06 100644 --- a/docs/more/development/document-templates/dev-notes.rst +++ b/docs/more/development/document-templates/dev-notes.rst @@ -34,7 +34,7 @@ Misplaced Content in PDF **Issue**: It may happen that content is placed over header/footer or incorrectly split between pages. -**Recommendations**: First, avoid incorrect HTML structures such as empty list items, nested paragraphs, tables without ``tbody`` etc. Then also make sure that the page, footer and header sizes are correctly set via CSS. Similarly, you can prevent page break using CSS. In case of issues, also refer to the :ref:`WeasyPrint step ` or directly the `WeasyPrint documentation `_. +**Recommendations**: First, avoid incorrect HTML structures such as empty list items, nested paragraphs, tables without ``tbody`` etc. Then also make sure that the page, footer and header sizes are correctly set via CSS. Similarly, you can prevent page break using CSS. In case of issues, also refer to the :ref:`WeasyPrint step ` or directly the `WeasyPrint documentation `_. Issues with PDF Formatting @@ -73,4 +73,3 @@ Compressing Images in MS Word Documents **Issue**: Uncompressed images in MS Word documents can significantly increase the file size, often making it much larger than the original HTML or PDF version. **Recommendations**: In the ``reference.docx`` document, you can adjust the image compression level to reduce the file size. To do this, open the document ``reference.docx`` and click on an image. Then, navigate to ``Picture Format`` -> ``Compress Pictures`` in the ``Adjust`` group. In the dialog box, you can select the desired compression level. Alternatively, you can set the default compression level for all images in the document. This will ensure that images are compressed when the document is saved. - \ No newline at end of file diff --git a/docs/more/development/document-templates/document-worker-plugins.rst b/docs/more/development/document-templates/document-worker-plugins.rst index 8d891c2..ea264a6 100644 --- a/docs/more/development/document-templates/document-worker-plugins.rst +++ b/docs/more/development/document-templates/document-worker-plugins.rst @@ -3,7 +3,7 @@ Document Worker Plugins ======================= -It is possible to extend functionality of |project_name| by implementing own plugins according to the instructions and thus add new features to the application. This requires technical knowledge and experience with the relevant technologies used in |project_name| (such as Python or Docker). You should not consider developing plugins unless you are familiar with programming and also will be committed to maintaining the plugin in the future. +It is possible to extend functionality of DSW by implementing own plugins according to the instructions and thus add new features to the application. This requires technical knowledge and experience with the relevant technologies used in DSW (such as Python or Docker). You should not consider developing plugins unless you are familiar with programming and also will be committed to maintaining the plugin in the future. .. note:: diff --git a/docs/more/development/document-templates/index.rst b/docs/more/development/document-templates/index.rst index 55a8aa1..bfaa2a7 100644 --- a/docs/more/development/document-templates/index.rst +++ b/docs/more/development/document-templates/index.rst @@ -3,7 +3,7 @@ Document Template Development ***************************** -Document templates allows to specify how to export a questionnaire in form of a textual file. It is a highly flexible element of the tool; however, the development requires basic programming skills with Jinja2 templating language. We can develop the document templates either on our local computer (traditional development with text editor or IDE) with use of the :doc:`./tdk` (TDK) or directly in |project_name| using :doc:`../../../application/document-templates/editors/index`. +Document templates allow us to specify how to export a questionnaire in the form of a textual file. It is a highly flexible element of the tool; however, the development requires basic programming skills with Jinja2 templating language. We can develop the document templates either on our local computer (traditional development with text editor or IDE) with use of the :doc:`./tdk` (TDK) or directly in DSW using :doc:`../../../application/document-templates/editors/index`. Every document template is based on the :doc:`template specification` and typically uses the :doc:`document context` to query information from a project (questionnaire replies, knowledge model, metadata, etc.) to create a document. diff --git a/docs/more/development/document-templates/specification.rst b/docs/more/development/document-templates/specification.rst index 3766c3e..5808043 100644 --- a/docs/more/development/document-templates/specification.rst +++ b/docs/more/development/document-templates/specification.rst @@ -3,7 +3,7 @@ Document Template Specification ******************************* -Each document template in |project_name| has metadata stored. If developing locally with :doc:`./tdk`, you can find and manage them in ``template.json`` file. In case of using :doc:`../../../application/document-templates/editors/index`, you can manage them on **Settings** tab. +Each document template in DSW has metadata stored. If developing locally with :doc:`./tdk`, you can find and manage them in ``template.json`` file. In case of using :doc:`../../../application/document-templates/editors/index`, you can manage them on **Settings** tab. Specification Structure @@ -17,10 +17,10 @@ Specification Structure * ``description`` = short description of the template * ``license`` = name of the used license * ``readme`` = longer description usually containing changelog -* ``metamodelVersion`` = supported version of template metamodel, it affects with which |project_name| version is can be used +* ``metamodelVersion`` = supported version of template metamodel, it affects with which DSW version is can be used * ``allowedPackages`` = list of package filters (see :ref:`document-template-package-filter`) to specify supported packages * ``formats`` = list of available formats (see below :ref:`document-template-format`) with specified steps for generation -* ``_tdk`` = TDK configuration for local development (not stored in |project_name|, see :ref:`tdk-config`) +* ``_tdk`` = TDK configuration for local development (not stored in DSW, see :ref:`tdk-config`) .. NOTE:: @@ -79,7 +79,7 @@ Each step of template produces output based on its (optional) input and options. TDK Config ---------- -Those are local-only metadata used for development of the template. You can use them in versioned ``template.json`` but those are never stored directly in |project_name|. +Those are local-only metadata used for development of the template. You can use them in versioned ``template.json`` but those are never stored directly in DSW. * ``version``: metadata version for needs of migrations * ``readmeFile``: files used to get content for ``readme`` of the template, usually ``README.md`` @@ -93,7 +93,7 @@ Document Template Metamodel Versions Here are described the changes in metamodel for template specification as well as :doc:`document context` so developers can easily update their templates to a newer metamodel version when needed. It is also possible to check JSON schemas in higher detail, see :doc:`../metamodel-schemas`. -Version 18.2 (since 4.31.0) +Version 18.2 (since 4.33.0) --------------------------- * Added: @@ -222,4 +222,4 @@ Version 2 (since 2.6.0) Version 1 (since 2.5.0) ----------------------- -* Initial version of metamodel, introduced in |project_name| 2.5.0 as start of versioning. +* Initial version of metamodel, introduced in DSW 2.5.0 as start of versioning. diff --git a/docs/more/development/document-templates/steps/excel.rst b/docs/more/development/document-templates/steps/excel.rst index 32a3fe8..209d7eb 100644 --- a/docs/more/development/document-templates/steps/excel.rst +++ b/docs/more/development/document-templates/steps/excel.rst @@ -74,7 +74,7 @@ Notes: - ``active_sheet`` is an index of sheet to be active when document is opened. - ``size`` sets the default `window size `__. -- ``tab_ratio`` sets `ratio `__ between the worksheet tabs and the horizontal slider. +- ``tab_ratio`` sets `ratio `__ between the worksheet tabs and the horizontal slider. Definitions ----------- @@ -170,17 +170,17 @@ The possible ``options`` are: `protect `__, `zoom `__, `tab_color `__, - `page_view `__, + `page_view `__, `select `__, `hide `__ - Print: ``orientation`` - (`landspace `__ + (`landscape `__ or - `portrait `__), - `paper `__, - `margins `__, - `header `__, - `footer `__, + `portrait `__), + `paper `__, + `margins `__, + `header `__, + `footer `__, `center_horizontally `__, `center_vertically `__ @@ -207,17 +207,17 @@ The possible ``options`` are: `protect `__, `zoom `__, `tab_color `__, - `page_view `__, + `page_view `__, `select `__, `hide `__ - Print (common): ``orientation`` - (`landspace `__ + (`landscape `__ or - `portrait `__), - `paper `__, - `margins `__, - `header `__, - `footer `__, + `portrait `__), + `paper `__, + `margins `__, + `header `__, + `footer `__, `center_horizontally `__, `center_vertically `__ - Basic: @@ -433,4 +433,3 @@ Example .. |badge-status| image:: https://img.shields.io/badge/status-stable-green .. |badge-metamodel| image:: https://img.shields.io/badge/metamodel%20version-%E2%89%A5%2011-blue - diff --git a/docs/more/development/document-templates/steps/jinja.rst b/docs/more/development/document-templates/steps/jinja.rst index 57c139e..3d2056a 100644 --- a/docs/more/development/document-templates/steps/jinja.rst +++ b/docs/more/development/document-templates/steps/jinja.rst @@ -26,7 +26,7 @@ Options Optional: -- ``jinja-ext`` = comma-separated list of `Jinja2 extensions `__ to be enabled (supported values: ``debug``) +- ``jinja-ext`` = comma-separated list of `Jinja2 extensions `__ to be enabled (supported values: ``debug``) - ``i18n-dir`` = location (relative to template root) of translations - ``i18n-domain`` = domain string of translations - ``i18n-lang`` = language code used in the template @@ -113,12 +113,12 @@ Every ``Asset`` object returned by ``assets()`` function has the following attri Filters ------- -Within Jinja templates, you can use so-called `filters `__.Basically, those are functions applied to a first argument using pipe ``|`` symbol. +Within Jinja templates, you can use so-called `filters `__. Basically, those are functions applied to a first argument using pipe ``|`` symbol. Builtin Filters ~~~~~~~~~~~~~~~ -There are several widely used `builtin filters `__ directly in Jinja. +There are several widely used `builtin filters `__ directly in Jinja. Value Conversion ~~~~~~~~~~~~~~~~ @@ -240,7 +240,7 @@ These filters are more complex and add various support to template development. Tests ----- -Within Jinja templates, you can use so-called `tests `__. Basically, those are helpers usable in conditions after ``is`` keyword: +Within Jinja templates, you can use so-called `tests `__. Basically, those are helpers usable in conditions after ``is`` keyword: .. code:: jinja @@ -252,7 +252,7 @@ Within Jinja templates, you can use so-called `tests `__ directly in Jinja. +There are several widely used `builtin tests `__ directly in Jinja. Custom Tests ~~~~~~~~~~~~ @@ -312,7 +312,7 @@ Notes ===== - All paths (e.g. for ``import`` or ``extends`` in Jinja2 templates are relative from the template root, i.e. directory with ``template.json``). -- The ``do`` `Jinja2 extension `__ is enabled. +- The ``do`` `Jinja2 extension `__ is enabled. - Using file extension ``.j2`` or ``.jinja2`` for templates is just a convention. - The :doc:`document context <../document-context>` is provided in ``ctx`` variable, other variables, filters, and tests are documented in other documents. diff --git a/docs/more/development/document-templates/tdk.rst b/docs/more/development/document-templates/tdk.rst index 92154fd..2334d99 100644 --- a/docs/more/development/document-templates/tdk.rst +++ b/docs/more/development/document-templates/tdk.rst @@ -9,7 +9,7 @@ Template Development Kit * Your favorite text editor or IDE * Template Development Kit (see below) - * |project_name| instance (recommended to have local one) with your admin account + * DSW instance (recommended to have local one) with your admin account * Python 3.10+ (with pip) or Docker Our Template Development Kit (TDK) provides a simple way how to work with templates locally. It is a CLI tool written in Python. @@ -49,11 +49,11 @@ Commands There are these basic commands: * ``config`` = manage shared user configuration (~/.dsw-tdk). -* ``get`` = download a template project with specified template ID from |project_name| -* ``list`` = list all templates (latest versions) from configured |project_name| +* ``get`` = download a template project with specified template ID from DSW +* ``list`` = list all templates (latest versions) from configured DSW * ``new`` = create a new template project, it launches a simple interactive wizard for template metadata -* ``package`` = create a ZIP distribution package from the local template project (ZIP is importable to |project_name| via its web interface) -* ``put`` = upload the local template project to |project_name| (once or continually on-change when ``--watch`` flag is used) +* ``package`` = create a ZIP distribution package from the local template project (ZIP is importable to DSW via its web interface) +* ``put`` = upload the local template project to DSW (once or continually on-change when ``--watch`` flag is used) * ``unpackage`` = extract a ZIP distribution package into the local template project directory * ``verify`` = check the metadata of the local template project @@ -72,7 +72,7 @@ Environment variables and .env file You can use environment variables to authenticate: -* ``DSW_API_URL`` = URL of |project_name| API with which you want to communicate. Hover mouse over your profile name to find the :ref:`About` section where URL is specified. +* ``DSW_API_URL`` = URL of DSW API with which you want to communicate. Hover mouse over your profile name to find the :ref:`About` section where URL is specified. * ``DSW_API_KEY`` = your :ref:`API Key`. Hover mouse over your profile name, click on :guilabel:`User Settings` and then navigate to :guilabel:`API Keys` From there, you can generate a new API Key for the authentication. To make this even easier, you can store those in ``.env`` file in the project root and it will be loaded automatically. Or you can specify the path to a ``.env`` file: diff --git a/docs/more/development/index.rst b/docs/more/development/index.rst index ddc281a..8349c55 100644 --- a/docs/more/development/index.rst +++ b/docs/more/development/index.rst @@ -1,9 +1,9 @@ Development *********** -|project_name| can be extended in many ways and new components and ways of integrations can be developed to support our needs. Besides the API available for everything that can be done in |project_name|, :ref:`integration questions` and :ref:`plugins` can be implemented to get data from outside to |project_name|, or new :ref:`document templates` and :ref:`submission services` can be created to get the data outside of |project_name| in the desired form. +DSW can be extended in many ways and new components and ways of integrations can be developed to support our needs. Besides the API available for everything that can be done in DSW, :ref:`integration questions` and :ref:`plugins` can be implemented to get data from outside to DSW, or new :ref:`document templates` and :ref:`submission services` can be created to get the data outside of DSW in the desired form. -This section provides information on how to develop custom content for |project_name| to fully tailor the tool to our specific requirements. +This section provides information on how to develop custom content for DSW to fully tailor the tool to our specific requirements. ---- diff --git a/docs/more/development/integration-questions/index.rst b/docs/more/development/integration-questions/index.rst index 88eb26a..01ebaf5 100644 --- a/docs/more/development/integration-questions/index.rst +++ b/docs/more/development/integration-questions/index.rst @@ -3,11 +3,11 @@ Integration Questions ********************* -|project_name| can be integrated with other services using so called :ref:`integration question`. The answer to that type of question does not contain only the answer itself but also a link to that external resource (which can be done, for example, using a persistent identifier). Therefore, these answers help clearly understand what the researchers use and promotes interoperability. +DSW can be integrated with other services using so called :ref:`integration question`. The answer to that type of question does not contain only the answer itself but also a link to that external resource (which can be done, for example, using a persistent identifier). Therefore, these answers help clearly understand what the researchers use and promotes interoperability. Examples of such integrations that are used within `Common DSW Knowledge Model `_ is `FAIRsharing `_ or `ROR `_. -There are two ways of how we can connect |project_name| to these services: +There are two ways of how we can connect DSW to these services: - **API** - using an API provided by the external service to search for the results diff --git a/docs/more/development/integration-questions/integration-api.rst b/docs/more/development/integration-questions/integration-api.rst index 7183a88..c23848d 100644 --- a/docs/more/development/integration-questions/integration-api.rst +++ b/docs/more/development/integration-questions/integration-api.rst @@ -1,7 +1,7 @@ Integration Question - API ************************** -:ref:`Integration question` can be connected to an external resource using its API. We can then search for the results from the external service using the |project_name| questionnaire interface. When we select an answer it is not only the text (such as a name of the database), but also a link to the external service to the selected item. The whole flow is denoted in the following diagram. +:ref:`Integration question` can be connected to an external resource using its API. We can then search for the results from the external service using the DSW questionnaire interface. When we select an answer it is not only the text (such as a name of the database), but also a link to the external service to the selected item. The whole flow is denoted in the following diagram. We can use `Jinja2 templating language `_ to construct everything in integrations. We also have this :ref:`cheatsheet` available. @@ -13,7 +13,7 @@ We can use `Jinja2 templating language `__ | Language field added | 4.33.0 | +| 18.2 | *(not published in dsw-schemas)* | Language field added | 4.33.0 | +-------------------+--------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------+--------+ -| 18.1 | `JSON Schema `__ | Python datetime and zoneinfo support | 4.31.0 | +| 18.1 | *(not published in dsw-schemas)* | Python datetime and zoneinfo support | 4.31.0 | +-------------------+--------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------+--------+ | 18.0 | `JSON Schema `__ | Renaming project and KM package, PluginIntegration | 4.29.0 | +-------------------+--------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------+--------+ @@ -109,14 +109,14 @@ Document Context is provided to the document templates by document worker. It co Template (.json file) ===================== -Each template has its descriptor file ``template.json`` which contains all the information about the template, its format(s) and steps how to produce the document(s). It is also versioned by the Template metamodel version number. This file also contains the actual number of the supported version... With local :doc:`./document-templates/index`, we will need to manage the file according to the schema; however, when :doc:`../../application/document-templates/editors/index` are used, we will define it using forms directly in |project_name|. +Each template has its descriptor file ``template.json`` which contains all the information about the template, its format(s) and steps how to produce the document(s). It is also versioned by the Template metamodel version number. This file also contains the actual number of the supported version... With local :doc:`./document-templates/index`, we will need to manage the file according to the schema; however, when :doc:`../../application/document-templates/editors/index` are used, we will define it using forms directly in DSW. +-------------------+------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------+--------+ | Metamodel Version | Schema file | Changes (brief) | Since | +===================+==============================================================================================================================+=============================================================+========+ | 18.2 | `JSON Schema `__ | Language field added | 4.33.0 | +-------------------+------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------+--------+ -| 18.1 | `JSON Schema `__ | Python datetime and zoneinfo support | 4.31.0 | +| 18.1 | *(not published in dsw-schemas)* | Python datetime and zoneinfo support | 4.31.0 | +-------------------+------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------+--------+ | 18.0 | `JSON Schema `__ | Renaming project and KM package, PluginIntegration | 4.29.0 | +-------------------+------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------+--------+ diff --git a/docs/more/development/plugins.rst b/docs/more/development/plugins.rst index 18604d1..d02497b 100644 --- a/docs/more/development/plugins.rst +++ b/docs/more/development/plugins.rst @@ -8,15 +8,15 @@ Plugins The plugins functionality is considered experimental. -This page provides information on how to develop plugins for |project_name|. Information on installing plugins can be found here: :ref:`plugins installation`. +This page provides information on how to develop plugins for DSW. Information on installing plugins can be found here: :ref:`plugins installation`. -If we want to extend |project_name| with new features, we can create plugins that will add the desired functionality. +If we want to extend DSW with new features, we can create plugins that will add the desired functionality. -To develop a plugin, we will need the DSW Plugin SDK, which is a library that will help us create, test, and deploy plugins for |project_name|. The SDK provides a framework for building plugins, as well as documentation and examples to get us started. The DSW Plugin SDK can be found here: https://github.com/ds-wizard/dsw-plugin-sdk. +To develop a plugin, we will need the DSW Plugin SDK, which is a library that will help us create, test, and deploy plugins for DSW. The SDK provides a framework for building plugins, as well as documentation and examples to get us started. The DSW Plugin SDK can be found here: https://github.com/ds-wizard/dsw-plugin-sdk. There are two templates we can use to create a new plugin: -- **DSW Plugin Template**: https://github.com/ds-wizard/dsw-plugin-template - to create plugins that extend |project_name| functionality using only the frontend part. +- **DSW Plugin Template**: https://github.com/ds-wizard/dsw-plugin-template - to create plugins that extend DSW functionality using only the frontend part. - **DSW Plugin Service Template**: https://github.com/ds-wizard/dsw-plugin-service-template - to create plugins that also have a backend service part. If we want to create a plugin using the backend service part, we can either use the Engine Gateway or create a new service from scratch using our preferred framework. The Engine Gateway has its own documentation here: https://github.com/ds-wizard/engine-gateway. diff --git a/docs/more/development/submission-service.rst b/docs/more/development/submission-service.rst index b6fb949..ce5e1cd 100644 --- a/docs/more/development/submission-service.rst +++ b/docs/more/development/submission-service.rst @@ -5,7 +5,7 @@ Submission Service Users with permission to manage settings can configure submission services using :doc:`../../application/administration/settings/content/document-submission`. The configured HTTP request is then used when a user clicks :guilabel:`Submit` for an allowed document for submission and selected the desired submission service. The document is sent as a body of the request (or as multipart, based on the configuration) to the external service that should process it and return HTTP response with status code, and possibly also the `Location` header and some textual message. -Usually, we will need a simple proxy service to be developed that will accommodate this to API of some information system, database, storage, or other service. For example, such a proxy service will be able to receive the JSON documents from |project_name|, retrieve additional information through |project_name| API as needed, transform it to some other resulting artifact and store it in some local database that is used by other systems. +Usually, we will need a simple proxy service to be developed that will accommodate this to API of some information system, database, storage, or other service. For example, such a proxy service will be able to receive the JSON documents from DSW, retrieve additional information through DSW API as needed, transform it to some other resulting artifact and store it in some local database that is used by other systems. Example Submission Services =========================== diff --git a/docs/more/development/vulnerabilities.rst b/docs/more/development/vulnerabilities.rst index 2da48ab..7c6b514 100644 --- a/docs/more/development/vulnerabilities.rst +++ b/docs/more/development/vulnerabilities.rst @@ -39,7 +39,7 @@ Basic Hints for Security * Change or remove default users * Adjust default role after registrations based on your needs -* Provide |project_name| through proxy with HTTPS (both client and server application) +* Provide DSW through proxy with HTTPS (both client and server application) * Backup data regularly (e.g. daily) * Use secured SMTP (SSL) * Use strong passwords, esp. for administrator accounts diff --git a/docs/more/miscellaneous/dsw-registry.rst b/docs/more/miscellaneous/dsw-registry.rst index d5317bd..b4acb35 100644 --- a/docs/more/miscellaneous/dsw-registry.rst +++ b/docs/more/miscellaneous/dsw-registry.rst @@ -3,14 +3,14 @@ DSW Registry ************ -`DSW Registry `_ is a place where we publish knowledge models, document templates and locales. It is very easy to get those into a |project_name| instance and use. +`DSW Registry `_ is a place where we publish knowledge models, document templates and locales. It is very easy to get those into a DSW instance and use. .. figure:: dsw-registry/dsw-registry.png DSW Registry with a list of knowledge models. -We first need to connect our |project_name| instance to the DSW Registry in :ref:`DSW Registry Settings`. Once we have that, we can: +We first need to connect our DSW instance to the DSW Registry in :ref:`DSW Registry Settings`. Once we have that, we can: - :ref:`Import knowledge models from DSW Registry` - :ref:`Import document templates from DSW Registry` diff --git a/docs/more/miscellaneous/help.rst b/docs/more/miscellaneous/help.rst index bf5d81a..2e63ffc 100644 --- a/docs/more/miscellaneous/help.rst +++ b/docs/more/miscellaneous/help.rst @@ -8,6 +8,6 @@ Still need help? Or you think that some topic is missing? Do not hesitate to con The best way to reach us is by sending an email to info@ds-wizard.org. -In case you found a bug, vulnerability, or have a generic question related directly to |project_name| tool - please `create a GitHub issue `__ and also visit :doc:`../development/contributing` section. +In case you found a bug, vulnerability, or have a generic question related directly to DSW tool - please `create a GitHub issue `__ and also visit :doc:`../development/contributing` section. For feature requests, we recommend using the `Ideas page `__. diff --git a/docs/more/miscellaneous/index.rst b/docs/more/miscellaneous/index.rst index 7c71bb8..15c09f3 100644 --- a/docs/more/miscellaneous/index.rst +++ b/docs/more/miscellaneous/index.rst @@ -1,7 +1,7 @@ Miscellaneous ************* -Additional information related to |project_name| that might be useful. +Additional information related to DSW that might be useful. ---- diff --git a/docs/more/miscellaneous/jinja-cheatsheet.rst b/docs/more/miscellaneous/jinja-cheatsheet.rst index 70588b3..ff739a3 100644 --- a/docs/more/miscellaneous/jinja-cheatsheet.rst +++ b/docs/more/miscellaneous/jinja-cheatsheet.rst @@ -3,7 +3,7 @@ Jinja Cheatsheet **************** -We can use Jinja templating language in :guilabel:`Response Item Template` and in :guilabel:`Response Item Template for Selection` (under :guilabel:`Advanced Response Configuration`) fields in |project_name|. Here you can get a basic overview of what can be achieved with Jinja. +We can use Jinja templating language in :guilabel:`Response Item Template` and in :guilabel:`Response Item Template for Selection` (under :guilabel:`Advanced Response Configuration`) fields in DSW. Here you can get a basic overview of what can be achieved with Jinja. For more information about Jinja templating language, visit the `official Jinja documentation `_. diff --git a/docs/more/miscellaneous/markdown-cheatsheet.rst b/docs/more/miscellaneous/markdown-cheatsheet.rst index b581d2d..a4bac2b 100644 --- a/docs/more/miscellaneous/markdown-cheatsheet.rst +++ b/docs/more/miscellaneous/markdown-cheatsheet.rst @@ -3,7 +3,7 @@ Markdown Cheatsheet ******************* -Various text fields in |project_name| can be formatted by using Markdown formatting language. Here you can get a basic overview of what can be achieved with Markdown. +Various text fields in DSW can be formatted by using Markdown formatting language. Here you can get a basic overview of what can be achieved with Markdown. Basic Syntax ============ @@ -163,7 +163,7 @@ These are the basic Markdown elements supported by all applications. Extended Syntax =============== -These elements extending the basic syntax are supported in |project_name|. +These elements extending the basic syntax are supported in DSW. .. raw:: html diff --git a/docs/more/self-hosted-dsw/configuration/configuration.rst b/docs/more/self-hosted-dsw/configuration/configuration.rst index 69b1762..b552154 100644 --- a/docs/more/self-hosted-dsw/configuration/configuration.rst +++ b/docs/more/self-hosted-dsw/configuration/configuration.rst @@ -55,7 +55,7 @@ This configuration section is used only by **Server** and covers basic configura If we need to change our ``secret``, we need also replace all values encrypted by the secret that is stored in the database as follows: 1. Note somewhere values from Settings: Client ID and Client Secret of OpenID configurations, Registry token, etc. Adjust the settings that the values are not there (recommended; e.g., remove OpenID configuration), and save it. -2. Change the ``secret`` in the configuration file and restart the |project_name| server (re-create the container if using Docker). +2. Change the ``secret`` in the configuration file and restart the DSW server (re-create the container if using Docker). 3. Adjust the settings back to our previous values. 4. If we also use some “user properties” (for the Document Submission feature), let our users know to change the values in their profiles. @@ -99,7 +99,7 @@ Information for connection to S3 storage (used for document and document templat :type: String :default: ``engine-wizard`` - Bucket name used by |project_name| + Bucket name used by DSW .. WARNING:: @@ -129,7 +129,7 @@ This configuration section is used only by **Mailer**. It must be filled with SM :type: String - Name of the |project_name| instance that will be used as “senders name” in email headers. + Name of the DSW instance that will be used as “senders name” in email headers. .. confval:: mail.email @@ -280,7 +280,7 @@ This configuration section is used only by **Document Worker**. It allows us to :type: String :default: ``Data Stewardship Wizard`` - Name of the service operating the |project_name| instance. + Name of the service operating the DSW instance. .. confval:: documentContext.serviceNameShort @@ -288,7 +288,7 @@ This configuration section is used only by **Document Worker**. It allows us to :type: String :default: ``DSW`` - Short name of the service operating the |project_name| instance. + Short name of the service operating the DSW instance. .. confval:: documentContext.serviceUrl @@ -296,7 +296,7 @@ This configuration section is used only by **Document Worker**. It allows us to :type: String :default: ``https://ds-wizard.org`` - URL of the service operating the |project_name| instance. + URL of the service operating the DSW instance. .. confval:: documentContext.serviceDomainName @@ -304,7 +304,7 @@ This configuration section is used only by **Document Worker**. It allows us to :type: String :default: ``ds-wizard.org`` - Domain name of the service operating the |project_name| instance. + Domain name of the service operating the DSW instance. .. confval:: documentContext.defaultPrimaryColor @@ -352,7 +352,7 @@ This configuration section is used only by **Document Worker**. It allows us to Integrations Configuration ========================== -Integrations in the |project_name| use external APIs. Sometimes, we might need some configured variables, such as API keys or endpoints. For example, integration with ID ``dbase`` might use the following configuration. +Integrations in the DSW use external APIs. Sometimes, we might need some configured variables, such as API keys or endpoints. For example, integration with ID ``dbase`` might use the following configuration. .. CODE-BLOCK:: yaml @@ -372,7 +372,7 @@ There can be multiple integrations configured in a single file. These can be use Client Configuration ==================== -If we are running the client app using “With Docker”, the all we need is to specify ``API_URL`` environment variable inside ``docker-compose.yml``. In case we want to run the client locally, we need to create a ``config.js`` file in the project root: +If we are running the client app using “With Docker”, all we need is to specify the ``API_URL`` environment variable inside ``docker-compose.yml``. In case we want to run the client locally, we need to create a ``config.js`` file in the project root: .. CODE-BLOCK:: javascript @@ -458,4 +458,3 @@ Once we have the file ready, we need to mount it into the container: dsw-client: volumes: - /path/to/head-extra.html:/src/head-extra.html - diff --git a/docs/more/self-hosted-dsw/configuration/document-templates.rst b/docs/more/self-hosted-dsw/configuration/document-templates.rst index 7e9308c..98d32c4 100644 --- a/docs/more/self-hosted-dsw/configuration/document-templates.rst +++ b/docs/more/self-hosted-dsw/configuration/document-templates.rst @@ -3,4 +3,4 @@ Document Templates ****************** -We can freely customize and style templates of documents (DMPs). HTML and CSS knowledge is required, and for doing more complex templates that use some conditions, loops, or macros, knowledge of `Jinja templating language `__ (pure Python implementation) is useful. For more information, please read :ref:`the following section`. +We can freely customize and style templates of documents (DMPs). HTML and CSS knowledge is required, and for doing more complex templates that use some conditions, loops, or macros, knowledge of `Jinja templating language `__ (pure Python implementation) is useful. For more information, please read :ref:`the following section`. diff --git a/docs/more/self-hosted-dsw/configuration/email-templates.rst b/docs/more/self-hosted-dsw/configuration/email-templates.rst index 57e32a1..50f2e9f 100644 --- a/docs/more/self-hosted-dsw/configuration/email-templates.rst +++ b/docs/more/self-hosted-dsw/configuration/email-templates.rst @@ -3,7 +3,7 @@ Email Templates *************** -Similarly to document templates, we can customize templates for emails sent by the Wizard located in ``templates`` folder. It also uses `Jinja templating language `__. And we can create HTML template, Plain Text template, add attachments, and add inline images (which can be used inside the HTML using `Content-ID `__ equal to the filename). We can learn more about the template structure and contents directly from `the mailer GitHub repository `__. +Similarly to document templates, we can customize templates for emails sent by the Wizard located in ``templates`` folder. It also uses `Jinja templating language `__. And we can create HTML template, Plain Text template, add attachments, and add inline images (which can be used inside the HTML using `Content-ID `__ equal to the filename). We can learn more about the template structure and contents directly from `the mailer GitHub repository `__. Including our own email templates while using dockerized Wizard is practically the same as for DMP templates. We can also bind whole ``templates`` folders. (or even ``templates`` if we want to change both): @@ -19,4 +19,3 @@ Including our own email templates while using dockerized Wizard is practically t - ./config/application.yml:/app/config/application.yml:ro - ./templates:/home/user/templates:ro # ... (continued) - diff --git a/docs/more/self-hosted-dsw/configuration/index.rst b/docs/more/self-hosted-dsw/configuration/index.rst index c7ab366..f9fdc15 100644 --- a/docs/more/self-hosted-dsw/configuration/index.rst +++ b/docs/more/self-hosted-dsw/configuration/index.rst @@ -1,7 +1,7 @@ Configuration ************* -This section explains how to configure |project_name| instance on your own. +This section explains how to configure DSW instance on your own. .. _config-settings: diff --git a/docs/more/self-hosted-dsw/configuration/plugins.rst b/docs/more/self-hosted-dsw/configuration/plugins.rst index c38fcae..ca44109 100644 --- a/docs/more/self-hosted-dsw/configuration/plugins.rst +++ b/docs/more/self-hosted-dsw/configuration/plugins.rst @@ -8,7 +8,7 @@ Plugins The plugins functionality is considered experimental. -This page provides information on how to install plugins for |project_name|. Information on developing plugins can be found here: :ref:`plugins development`. +This page provides information on how to install plugins for DSW. Information on developing plugins can be found here: :ref:`plugins development`. There are available plugins to extend the functionality of the base DSW. diff --git a/docs/more/self-hosted-dsw/deployment.rst b/docs/more/self-hosted-dsw/deployment.rst index d51f558..977ac17 100644 --- a/docs/more/self-hosted-dsw/deployment.rst +++ b/docs/more/self-hosted-dsw/deployment.rst @@ -4,7 +4,7 @@ Deployment ********** -Own |project_name| Instance +Own DSW Instance =========================== .. WARNING:: @@ -23,7 +23,7 @@ The simplest way is to use `Docker Compose `__ 1. Clone the `DSW Deployment Example `__ repository 2. Check config files (described in :doc:`./configuration/configuration`) -3. Run the |project_name| with Docker compose ``docker-compose up -d`` +3. Run the DSW with Docker compose ``docker-compose up -d`` 4. After starting up, we will be able to open the Wizard in our browser on http://localhost:8080 5. We can use ``docker-compose logs`` to see the logs and ``docker-compose down`` to stop all the services @@ -55,16 +55,16 @@ We can use those accounts for testing or initially make our own admin account an .. WARNING:: - Having a public instance with default accounts is a **security risk**. We should delete or change default accounts (mainly Albert Einstein) if our |project_name| instance is public as soon as possible. + Having a public instance with default accounts is a **security risk**. We should delete or change default accounts (mainly Albert Einstein) if our DSW instance is public as soon as possible. .. NOTE:: - Do not use UIDs below 10000 as that might introduce a `security risk `__. + Do not use UIDs below 10000 as that might introduce a `security risk `__. DSW Registry ------------ -When we have our own self-hosted instance, it is essential to register within the `DSW Registry `__. It is a source of shared knowledge models, document templates, and locales that can support our deployment. The registry is also integrated inside the |project_name|. Therefore, we can easily pull new versions from the |project_name|. The registration can be done either directly in our |project_name| instance in Settings or via the DSW Registry website. +When we have our own self-hosted instance, it is essential to register within the `DSW Registry `__. It is a source of shared knowledge models, document templates, and locales that can support our deployment. The registry is also integrated inside the DSW. Therefore, we can easily pull new versions from the DSW. The registration can be done either directly in our DSW instance in Settings or via the DSW Registry website. Initial Knowledge Model, Document Templates, and Locales @@ -82,7 +82,7 @@ If we want to regularly backup our database (and we should!), all we need to do Deployment Requirements ----------------------- -The following requirements were estimated using `limiting Docker resources `__ provided to containers. +The following requirements were estimated using `limiting Docker resources `__ provided to containers. +-----------------+----------------+----------------+ | Component | Minimal | Recommended | diff --git a/docs/more/self-hosted-dsw/faq-notes.rst b/docs/more/self-hosted-dsw/faq-notes.rst index bb610e2..d22ad14 100644 --- a/docs/more/self-hosted-dsw/faq-notes.rst +++ b/docs/more/self-hosted-dsw/faq-notes.rst @@ -19,7 +19,7 @@ Why I cannot upload locales/templates and document generation fails? You probably have some issue with S3 configuration or its deployment. Also, check whether you have S3 bucket present with correct name. -Why I cannot download files from |project_name| or generate document preview? +Why I cannot download files from DSW or generate document preview? ----------------------------------------------------------------------------- Your S3 is probably not accessible by users. The S3 URL configured in :ref:`config-server` should be reachable so users can download something from the storage. @@ -32,9 +32,9 @@ Please use the `PostgreSQL documentation `_ to There is some issue with the MinIO S3 storage; what should I do? ---------------------------------------------------------------- -Please use the `MinIO documentation `_ to check the cause, various things may have happened... especially if you tried to upgrade the storage version. +Please use the `MinIO documentation `_ to check the cause, various things may have happened... especially if you tried to upgrade the storage version. -I upgraded |project_name| and now it does not work properly, what should I do? +I upgraded DSW and now it does not work properly, what should I do? ------------------------------------------------------------------------------ You should always check :doc:`upgrade-guidelines` before upgrading, be sure that you followed all steps. In case you forgot and it is not possible to fix it now, you will have to rollback from you backup and do it again by following the guidelines this time. In case you encounter an issue even though you followed the guidelines, that might a bug and please `report it `_. @@ -49,9 +49,9 @@ There are two cases: - You are using a document template from DSW Registry. - You are using your own document template. -For the first case, you need to import newer version from DSW Registry. Templates in Registry are managed by the DSW Team which ensure that they are always up to date. If those are your own document templates, you need to update them according to :ref:`document-template-metamodel-versions`. +For the first case, you need to import a newer version from DSW Registry. Templates in Registry are managed by the DSW Team which ensures that they are always up to date. If those are your own document templates, you need to update them according to :ref:`document-template-metamodel-versions`. -To update from DSW Registry, you need to have in connected with your DSW instance. If you can see the :guilabel:`Update Available` badge, you can update the template. If you cannot see the badge, you should check if you are connected to the DSW Registry. +To update from DSW Registry, you need to have it connected with your DSW instance. If you can see the :guilabel:`Update Available` badge, you can update the template. If you cannot see the badge, you should check if you are connected to the DSW Registry. To connect to the DSW Registry and import new templates from there, you can follow this guide: @@ -79,6 +79,6 @@ Deployment Notes - You should be knowledgeable with at least basics of server management, service operations, work with Docker, and debugging issues (e.g. accessing Docker logs). - The deployment can vary significantly based on needs and available infrastructure, we cannot help with different kinds of deployments and technologies that we are not experts with. -- The deployment example serves for local testing purposes and should not be used as is for production. An expert should deploy |project_name| for production while considering local needs and capabilities. +- The deployment example serves for local testing purposes and should not be used as is for production. An expert should deploy DSW for production while considering local needs and capabilities. - Never update production instance without backups and preferably try the update procedure first on a testing environment. -- Running |project_name| locally is not "free", you need people, time, and infrastructure. With that in mind, consider what `option `_ is the most suitable for you. +- Running DSW locally is not "free", you need people, time, and infrastructure. With that in mind, consider what `option `_ is the most suitable for you. diff --git a/docs/more/self-hosted-dsw/index.rst b/docs/more/self-hosted-dsw/index.rst index 8e5ea2f..8dde7f3 100644 --- a/docs/more/self-hosted-dsw/index.rst +++ b/docs/more/self-hosted-dsw/index.rst @@ -1,11 +1,11 @@ -Self-Hosted |project_name| +Self-Hosted DSW ************************** -This section explains how to deploy, configure, and maintain |project_name| instance on your own. +This section explains how to deploy, configure, and maintain DSW instance on your own. .. NOTE:: - Before going for self-hosted options, it is a good idea to try out |project_name| using `existing providers `_. + Before going for self-hosted options, it is a good idea to try out DSW using `existing providers `_. .. raw:: html diff --git a/docs/more/self-hosted-dsw/upgrade-guidelines.rst b/docs/more/self-hosted-dsw/upgrade-guidelines.rst index 1f71aaf..34dd97a 100644 --- a/docs/more/self-hosted-dsw/upgrade-guidelines.rst +++ b/docs/more/self-hosted-dsw/upgrade-guidelines.rst @@ -3,7 +3,7 @@ Upgrade Guidelines ****************** -Upgrading |project_name| +Upgrading DSW ======================== .. Warning:: @@ -435,7 +435,7 @@ Before updating check following, otherwise the migration will fail: 2.5.X to 2.6.X -------------- -- The document templates including the default ``questionnaire-report`` must be updated from `https://registry.ds-wizard.org/templates `_. +- The document templates including the default ``questionnaire-report`` must be updated from the `DSW Registry `_. - Upgraded template metamodel version 2 requires manual migration of custom templates: - `questionnaireRepliesMap` (map path:Reply) is no longer present in the context @@ -465,8 +465,8 @@ Before updating check following, otherwise the migration will fail: 2.4.X to 2.5.X -------------- -- Document templates have been moved from FS to database. To simplify the transition for custom templates, we added to the Docker image a script that loads templates from FS to the database via |project_name| API. But there are several new information that we need to provide in ``template.json`` file: ``id`` (instead of ``uuid``), ``templateId``, ``organizationId``, ``version`` (semver), ``license``, ``readme`` (Markdown). The ``id`` should be in format ``organizationId:templateId:version``. Please note that this applies only for custom templates, default template can be removed from FS as it is added to the database automatically. The script must be enabled by setting envvar ``ENABLE_TEMPLATE_LOAD `` to ``1`` and ``SERVICE_TOKEN`` according to the configuration. -- Cron is no longer needed for the feedback synchronization (environment variables in ``docker-compose.yml``) as |project_name| schedules synchronization internally. +- Document templates have been moved from FS to database. To simplify the transition for custom templates, we added to the Docker image a script that loads templates from FS to the database via DSW API. But there are several new information that we need to provide in ``template.json`` file: ``id`` (instead of ``uuid``), ``templateId``, ``organizationId``, ``version`` (semver), ``license``, ``readme`` (Markdown). The ``id`` should be in format ``organizationId:templateId:version``. Please note that this applies only for custom templates, default template can be removed from FS as it is added to the database automatically. The script must be enabled by setting envvar ``ENABLE_TEMPLATE_LOAD `` to ``1`` and ``SERVICE_TOKEN`` according to the configuration. +- Cron is no longer needed for the feedback synchronization (environment variables in ``docker-compose.yml``) as DSW schedules synchronization internally. 2.3.X to 2.4.X -------------- @@ -482,7 +482,7 @@ Before updating check following, otherwise the migration will fail: 2.1.X to 2.2.X -------------- -- Configuration of client and several features is now moved from ``application.yml`` file to in-app settings. therefore, it must be reconfigured during upgrade process. Additional ``secret`` must be configured in ``application.yml`` for encryption and JWT tokens (*JWT.secret* section has been removed), see :ref:`config-server` configuration. It is recommended to first add *general.secret* (32 chars secret), start |project_name|, migrate options from ``application.yml`` in-app settings and then optionally clean up ``application.yml`` file. +- Configuration of client and several features is now moved from ``application.yml`` file to in-app settings. therefore, it must be reconfigured during upgrade process. Additional ``secret`` must be configured in ``application.yml`` for encryption and JWT tokens (*JWT.secret* section has been removed), see :ref:`config-server` configuration. It is recommended to first add *general.secret* (32 chars secret), start DSW, migrate options from ``application.yml`` in-app settings and then optionally clean up ``application.yml`` file. - User fields ``name`` and ``surname`` has been renamed to ``firstName`` and ``lastName`` - it needs be updated if used in **custom** mail or document templates. - Recommended version of MongoDB is updated to 4.2.3. @@ -495,7 +495,7 @@ Before updating check following, otherwise the migration will fail: --------------- - Changing the major version actually does not mean any problem in migration, it has been made due to significant internal changes (restructuring, new repositories, etc.) -- If we are using Docker for running |project_name|, we need to change it according to new documentation of :ref:`installation-docker` and :doc:`./configuration/configuration`. +- If we are using Docker for running DSW, we need to change it according to new documentation of :ref:`installation-docker` and :doc:`./configuration/configuration`. - Crontab image is no longer needed. - A DMP template configuration file must contain list of ``allowedKMs`` (see the default *root* template).