Merge pull request #164 from ds-wizard/release/4.10.0

Release 4.10.0
ds-wizard · Sep 4, 2024 · 652ffad · 652ffad
2 parents cf2a292 + f8ac2ba
commit 652ffad
Show file tree

Hide file tree

Showing 14 changed files with 8,775 additions and 251 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -22,4 +22,5 @@ watch:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	@rm -rf ./_build
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/about/introduction/knowledge-model.rst b/docs/about/introduction/knowledge-model.rst
@@ -40,7 +40,7 @@ The knowledge model consists of chapters at the top level. Each chapter has a **
 Question
 --------
 
-Questions are used to collect the answers from users. Each question has a **title** (the actual question), a **description**, a **phase** when it becomes desirable, a list of :ref:`references<reference>` and :ref:`experts<expert>`, and a selection of :ref:`question tags<question-tag>`.
+Questions are used to collect the answers from users. Each question has a **title** (the actual question), a **description**, a **phase** when it becomes desirable, a list of :ref:`resource pages<resource-page>` gathered in a :ref:`resource collection<resource-collection>` or :ref:`URL references<url-reference>` and :ref:`experts<expert>`, and a selection of :ref:`question tags<question-tag>`.
 
 Then there are some additional settings based on the **question type**.
 
@@ -101,6 +101,13 @@ Multi-Choice Question
 The multi-choice question has a list of :ref:`choices<choice>`. Users can then pick as many of those choices as they wish. There are, however, no follow-up questions available for this question type.
 
 
+.. _item-select-question:
+
+Item Select Question
+^^^^^^^^^^^^^^^^^^^^
+
+The item selection question works in conjunction with the :ref:`list of items question<list-of-items-question>`. It is used to select one of the previously created items within a series of interconnected list of items question.
+
 .. _answer:
 
 Answer
@@ -124,17 +131,26 @@ Choice
 A choice is used with :ref:`multi-choice questions<multi-choice-question>`. It only contains a **label** which is presented to the user.
 
 
-.. _reference:
+.. _resource-collection:
+
+Resource Collection
+--------------------
+
+We can provide some additional reference resources for :ref:`questions<question>` to help users better understand it or learn more details. There are two types of references.
+
+.. _resource-page:
+
+Resource Page Reference
+^^^^^^^^^^^^^^^^^^^^^^^
 
-Reference
----------
+A resource page reference is a link to a page in the |project_name| itself. It has **title** which is the name of the page and a **content** that describes what the reference is about. Resource pages are gathered in the resource collections.
 
-We can provide some additional references for :ref:`questions<question>` to help users better understand it or learn more details. There are more types of references.
+.. _url-reference:
 
 URL Reference
-^^^^^^^^^^^^^
+-------------
 
-A URL reference is a simple link to any website. It has **URL** which is the actual link and a **label** that describes what the reference is about.
+A URL reference is a simple link to any website. It has **URL** which is the actual link and a **label** that describes what the reference is about. URL reference is set up on a level of question, not on a level of knowledge model.
 
 Book Reference
 ^^^^^^^^^^^^^^
@@ -143,13 +159,6 @@ Book Reference
     Book references are deprecated.
 
 
-Resource Page Reference
-^^^^^^^^^^^^^^^^^^^^^^^
-
-.. warning::
-    Resource page references are not yet implemented.
-
-
 .. _expert:
 
 Expert

diff --git a/docs/about/introduction/knowledge-model/knowledge-model-schema.png b/docs/about/introduction/knowledge-model/knowledge-model-schema.png
diff --git a/docs/application/knowledge-models/editors/detail/knowledge-model.rst b/docs/application/knowledge-models/editors/detail/knowledge-model.rst
@@ -45,19 +45,18 @@ There are different entities we can edit in the knowledge model, the editor show
 - :ref:`Question<question>`
 - :ref:`Answer<answer>`
 - :ref:`Choice<choice>`
-- :ref:`Reference<reference>`
 - :ref:`Expert<expert>`
 - :ref:`Metric<metric>`
 - :ref:`Phase<phase>`
 - :ref:`Question Tag<question-tag>`
 - :ref:`Integration<integration>`
+- :ref:`Resource Collection<resource-collection>`
 
 .. figure:: knowledge-model/editor-form.png
 
     Example of question editor form.
 
 
-
 Besides their own fields, each entity has so called **Annotations**. They are arbitrary key value pairs that can be assigned to the entity and used later, when :ref:`developing a document template<document-template-development>`.
 
 

diff --git a/docs/application/projects/list/detail/questionnaire.rst b/docs/application/projects/list/detail/questionnaire.rst
@@ -38,7 +38,6 @@ There are three desirability states the question can be in:
     If there is no phase defined on the knowledge model, the current phase selection is not visible in the questionnaire detail.
 
 
-
 Chapters
 ========
 
@@ -108,6 +107,7 @@ There is a trash bin icon in the item's top right corner that we can use to **de
 
     List of items question with a single item.
 
+
 Value Question
 --------------
 
@@ -132,7 +132,6 @@ When we pick an answer from the list, we not only have the answer but also **a l
     Integration question with a response from FAIRsharing containing also a link.
 
 
-
 Multi-Choice Question
 ---------------------
 
@@ -143,6 +142,19 @@ Multi-choice question is similar to the options question, however we can choose
     Multi-choice question with many choices.
 
 
+Item Select Question
+--------------------
+
+The item selection question is used together with the list of items question. When creating an item selection question, you must choose one of the existing list of items questions. The answers provided to that list of items question are then offered as possible answers in the item selection question.
+
+.. TODO::
+
+    Add a screenshot of the item select question.
+
+.. .. figure:: questionnaire/item-select-question.png
+    
+..     Item select question with a list of items as possible answers.
+
 
 View settings
 =============

diff --git a/docs/conf.py b/docs/conf.py
@@ -25,7 +25,7 @@
 project_name_full = 'Data Stewardship Wizard'
 
 # The full version, including alpha/beta/rc tags
-version = release = '4.9'
+version = release = '4.10'
 
 rst_prolog = f"""
 

diff --git a/docs/more/development/document-templates/dev-notes.rst b/docs/more/development/document-templates/dev-notes.rst
@@ -0,0 +1,45 @@
+.. _document-template-dev-notes:
+
+Document Template Development Notes
+***********************************
+
+Here we collect general recommendations and best practices to develop document templates. In case you would like to include a specific notes, please let us know - any suggestions are appreciated.
+
+Missing or Special Fonts
+========================
+
+**Issue**: It may happen that certain fonts are not installed in the document worker (affecting PDF documents) or user's device (affecting client-rendered documents like HTML or SVG). This may result in weird/incorrect characters appearing incl. rectangular shapes.
+
+**Recommendations**: Include fonts via CSS/HTML, e.g. using the `Google Fonts <https://fonts.google.com/>`_ or other similar:
+
+.. code:: html
+
+    <head>
+        <title>Data Management Plan</title>
+        <meta charset="utf-8">
+        <link rel="preconnect" href="https://fonts.googleapis.com">
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+        <link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,100..900;1,100..900&family=Open+Sans:ital,wght@0,300..800;1,300..800&display=swap" rel="stylesheet">
+        <style>
+            body { font-family: "Open Sans", sans-serif; }
+        </style>
+    </head>
+
+
+It is not recommended to add fonts as part of the document template for performance and usage reasons.
+
+
+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 <document-template-step-weasyprint>` or directly the `WeasyPrint documentation <https://doc.courtbouillon.org/weasyprint/>`_.
+
+
+Styling MS Word Documents
+=========================
+
+**Issue**: CSS and HTML styling is not appearing correctly in MS Word documents (transformed from HTML via the Pandoc step).
+
+**Recommendations**: CSS styles do not affect resulting MS Word documents as that is not possible with Pandoc. The Word document will use the matching styles based on certain HTML tags (e.g. ``<title>``, ``<h1>``, ``<p>``, or ``<table>``). You can adjust how those look by creating ``reference.docx`` document with desired styles incl. headers/footers. Ideal way is to download MS Word document generated, adjust styles as needed, and store it as the ``reference.docx`` document. Then, it can be simply added to the document template and used for the :ref:`Pandoc step <document-template-step-pandoc>` via ``args``. Please check directly the `relevant part of the Pandoc documentation <https://pandoc.org/MANUAL.html#option--reference-doc>`_.