Merge pull request #95 from codevence/develop

Preview 4.10

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,14 @@ 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
@@ -129,26 +137,36 @@ A choice is used with :ref:`multi-choice questions<multi-choice-question>`. It o
 Reference
 ---------
 
-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.
+References are used to provide additional information for :ref:`questions<question>`. There are two types of references. :ref:`Resource page reference<resource-page>` and :ref:`URL reference<url-reference>`. resource page references are gathered in the resource collections.
+
+.. _resource-collection:
+
+Resource Collection
+^^^^^^^^^^^^^^^^^^^
+
+Resource collections are used to group together :ref:`resource pages<resource-page>` that are related to each other. Each resource collection has a **title** and has a list of resource pages. Resource collection is created on a level of a Knowledge Model.
 
+.. _resource-page:
+
+Resource Page
+^^^^^^^^^^^^^
+
+A resource page is a simple page that can be used to provide information for :ref:`questions<question>`. It has a **title** and a **content**. Resource pages are gathered in the :ref:`resource collections<resource-collection>`.
+
+.. _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
 ^^^^^^^^^^^^^^
 
 .. warning::
     Book references are deprecated.
 
-Resource Page Reference
-^^^^^^^^^^^^^^^^^^^^^^^
-
-.. warning::
-    Resource page references are not yet implemented.
-
 
 .. _expert:
 

docs/applications/analytics/knowledge-models.rst

@@ -23,6 +23,8 @@ Various fields have filters that can be used to narrow down the data.
 
 We can also resize all rows height by clicking on the double arrow in the top left corner. If we want to edit width or height of individual cells, we can do it using drag-and-drop on the borders. Lastly we can edit how many rows are on the page by clicking on the :guilabel:`Items per page` dropdown menu.
 
+The data of a view can be exported to a CSV file by clicking on :guilabel:`Export CSV`.
+
 .. NOTE::
 
     Don't forget to click on :guilabel:`Save` icon after you are done with editing the view.
@@ -36,12 +38,12 @@ The Knowledge Model details have four tabs. The :guilabel:`Readme` tab shows the
 
      Knowledge Model Editors created using this Knowledge Model.
 
-The last tab, :guilabel:`Insights`, is the most complex. It shows us detailed information for each question and answer, such as the number of times a certain question was displayed to users and how these questions were answered.
+
+The last tab, :guilabel:`Insights`, is the most complex. It shows us detailed information for each question and answer, such as the number of times a certain question was displayed to users and how these questions were answered. If we are viewing details of a value question, we can use search functionality to find the value we are interested in.
 
 Furthermore, we can also open various questions to see insights into how the Researchers are answering them.
 
  .. figure:: knowledge-models/insights.png
 
      Insights to usage of this Knowledge Model in Projects.
 
-The data of a view can be exported to a CSV file by clicking on :guilabel:`Export CSV`.

docs/applications/data-management-planner/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>`.
 
 

docs/applications/data-management-planner/projects/list/detail/questionnaire.rst

@@ -143,6 +143,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
 =============

docs/conf.py

@@ -26,7 +26,7 @@
 registry_name = 'FAIR Wizard Registry'
 
 # The full version, including alpha/beta/rc tags
-version = release = '4.9'
+version = release = '4.10'
 
 rst_prolog = f"""
 

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>`_.