diff --git a/docs/Makefile b/docs/Makefile index 404ecef..5c3d717 100644 --- 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 index 773f757..976c6a2 100644 --- 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` and :ref:`experts`, and a selection of :ref:`question tags`. +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` gathered in a :ref:`resource collection` or :ref:`URL references` and :ref:`experts`, and a selection of :ref:`question tags`. 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`. 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`. 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`. 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` 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` 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 index 44332aa..aa18e5c 100644 Binary files a/docs/about/introduction/knowledge-model/knowledge-model-schema.png and b/docs/about/introduction/knowledge-model/knowledge-model-schema.png differ diff --git a/docs/application/knowledge-models/editors/detail/knowledge-model.rst b/docs/application/knowledge-models/editors/detail/knowledge-model.rst index 3ca4d03..759f58e 100644 --- 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` - :ref:`Answer` - :ref:`Choice` -- :ref:`Reference` - :ref:`Expert` - :ref:`Metric` - :ref:`Phase` - :ref:`Question Tag` - :ref:`Integration` +- :ref:`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`. diff --git a/docs/application/projects/list/detail/questionnaire.rst b/docs/application/projects/list/detail/questionnaire.rst index 580e059..8431f96 100644 --- 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 index 5f55d12..6864b4e 100644 --- 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/metamodel-schemas.rst b/docs/more/development/metamodel-schemas.rst index 3364a20..2943dfe 100644 --- a/docs/more/development/metamodel-schemas.rst +++ b/docs/more/development/metamodel-schemas.rst @@ -11,72 +11,76 @@ KM Package (.km file) File for import and export of Knowledge Models is a JSON file that contains all KM packages (lists of change events with additional metadata). The structure of events is versioned using the KM metamodel version number and migrations in |project_name| automatically update the KMs when needed. As said, files according to this schema can be exported from :doc:`../../application/knowledge-models/list/index` or :doc:`../../application/knowledge-models/list/detail` and then used for :doc:`../../application/knowledge-models/list/import`. -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| Metamodel Version | Schema file | Changes (brief) | Since | -+===================+===============================================================================================================+=========================================+===========+ -| 14 | `JSON Schema `__ | Optional Integration fields | 4.1.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 13 | `JSON Schema `__ | New question value types | 3.12.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 12 | `JSON Schema `__ | Enhanced integration (e.g. widget type) | 3.10.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 11 | `JSON Schema `__ | Annotations and timestamps for events | 3.8.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 10 | `JSON Schema `__ | Integrations with item template | 3.6.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 9 | `JSON Schema `__ | Annotations | 3.5.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 8 | `JSON Schema `__ | Metrics and phases are part of KM | 3.2.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 7 | `JSON Schema `__ | KM name attribute removed | 2.13.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 6 | `JSON Schema `__ | Multi-choice question type added | 2.11.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 5 | `JSON Schema `__ | Move event | 2.0.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 4 | `JSON Schema `__ | Refactored KM, optional chapter text | 1.10.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 3 | `JSON Schema `__ | Changed integration question fields | 1.8.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 2 | `JSON Schema `__ | Changed phases representation | 1.7.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 1 | `JSON Schema `__ | Initial versioned metamodel | 1.6.0 | -+-------------------+---------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| Metamodel Version | Schema file | Changes (brief) | Since | ++===================+===============================================================================================================+======================================================+===========+ +| 15 | `JSON Schema `__ | Item select question, resource collections and pages | 4.10.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 14 | `JSON Schema `__ | Optional Integration fields | 4.1.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 13 | `JSON Schema `__ | New question value types | 3.12.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 12 | `JSON Schema `__ | Enhanced integration (e.g. widget type) | 3.10.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 11 | `JSON Schema `__ | Annotations and timestamps for events | 3.8.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 10 | `JSON Schema `__ | Integrations with item template | 3.6.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 9 | `JSON Schema `__ | Annotations | 3.5.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 8 | `JSON Schema `__ | Metrics and phases are part of KM | 3.2.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 7 | `JSON Schema `__ | KM name attribute removed | 2.13.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 6 | `JSON Schema `__ | Multi-choice question type added | 2.11.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 5 | `JSON Schema `__ | Move event | 2.0.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 4 | `JSON Schema `__ | Refactored KM, optional chapter text | 1.10.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 3 | `JSON Schema `__ | Changed integration question fields | 1.8.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 2 | `JSON Schema `__ | Changed phases representation | 1.7.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ +| 1 | `JSON Schema `__ | Initial versioned metamodel | 1.6.0 | ++-------------------+---------------------------------------------------------------------------------------------------------------+------------------------------------------------------+-----------+ Document Context ================ Document Context is provided to the document templates by document worker. It contains all relevant data about project/questionnaire with replies, related knowledge model, author, and more. As KM evolves, the context may evolve as well. It is versioned using the Template metamodel version number. A document template must support the metamodel that is in the current |project_name| instance. It is needed to know how the document context looks like especially for :doc:`./document-templates/index`. -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| Metamodel Version | Schema file | Changes (brief) | Since | -+===================+========================================================================================================================+=========================================+===========+ -| 13 | `JSON Schema `__ | Removed states from templates | 4.3.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 12 | `JSON Schema `__ | Optional Integration fields | 4.1.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 11 | `JSON Schema `__ | Change template metadata | 3.20.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 10 | `JSON Schema `__ | New question value types | 3.12.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 9 | `JSON Schema `__ | Enhanced integration (e.g. widget type) | 3.10.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 8 | `JSON Schema `__ | Annotations change | 3.8.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 7 | `JSON Schema `__ | Project tags and description | 3.7.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 6 | `JSON Schema `__ | Integrations with item template | 3.6.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 5 | `JSON Schema `__ | Annotations | 3.5.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 4 | `JSON Schema `__ | Metrics and phases | 3.2.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 3 | `JSON Schema `__ | Project versions | 2.12.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 2 | `JSON Schema `__ | Reply provenance | 2.6.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 1 | `JSON Schema `__ | Initial versioned metamodel | 2.5.0 | -+-------------------+------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| Metamodel Version | Schema file | Changes (brief) | Since | ++===================+========================================================================================================================+===================================================+===========+ +| 14 | `JSON Schema `__ | new KM entities, project details, and restructure | 4.10.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 13 | `JSON Schema `__ | Removed states from templates | 4.3.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 12 | `JSON Schema `__ | Optional Integration fields | 4.1.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 11 | `JSON Schema `__ | Change template metadata | 3.20.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 10 | `JSON Schema `__ | New question value types | 3.12.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 9 | `JSON Schema `__ | Enhanced integration (e.g. widget type) | 3.10.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 8 | `JSON Schema `__ | Annotations change | 3.8.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 7 | `JSON Schema `__ | Project tags and description | 3.7.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 6 | `JSON Schema `__ | Integrations with item template | 3.6.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 5 | `JSON Schema `__ | Annotations | 3.5.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 4 | `JSON Schema `__ | Metrics and phases | 3.2.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 3 | `JSON Schema `__ | Project versions | 2.12.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 2 | `JSON Schema `__ | Reply provenance | 2.6.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 1 | `JSON Schema `__ | Initial versioned metamodel | 2.5.0 | ++-------------------+------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ Template (.json file) ===================== @@ -87,32 +91,34 @@ Each template has its descriptor file ``template.json`` which contains all the i Between versions 1 and 5, the structure of ``template.json`` is still the same. Only the document context has been changed. -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| Metamodel Version | Schema file | Changes (brief) | Since | -+===================+============================================================================================================================+=========================================+===========+ -| 13 | `JSON Schema `__ | Removed states from templates | 4.3.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 12 | `JSON Schema `__ | Optional Integration fields | 4.1.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 11 | `JSON Schema `__ | Change template metadata | 3.20.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 10 | `JSON Schema `__ | New question value types | 3.12.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 9 | `JSON Schema `__ | Enhanced integration (e.g. widget type) | 3.10.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 8 | `JSON Schema `__ | Annotations change | 3.8.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 7 | `JSON Schema `__ | Project tags and description | 3.7.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 6 | `JSON Schema `__ | Integrations with item template | 3.6.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 5 | `JSON Schema `__ | Annotations | 3.5.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 4 | `JSON Schema `__ | Metrics and phases | 3.2.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 3 | `JSON Schema `__ | Project versions | 2.12.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 2 | `JSON Schema `__ | Reply provenance | 2.6.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ -| 1 | `JSON Schema `__ | Initial versioned metamodel | 2.5.0 | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+-----------------------------------------+-----------+ ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| Metamodel Version | Schema file | Changes (brief) | Since | ++===================+============================================================================================================================+===================================================+===========+ +| 14 | `JSON Schema `__ | new KM entities, project details, and restructure | 4.10.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 13 | `JSON Schema `__ | Removed states from templates | 4.3.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 12 | `JSON Schema `__ | Optional Integration fields | 4.1.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 11 | `JSON Schema `__ | Change template metadata | 3.20.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 10 | `JSON Schema `__ | New question value types | 3.12.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 9 | `JSON Schema `__ | Enhanced integration (e.g. widget type) | 3.10.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 8 | `JSON Schema `__ | Annotations change | 3.8.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 7 | `JSON Schema `__ | Project tags and description | 3.7.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 6 | `JSON Schema `__ | Integrations with item template | 3.6.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 5 | `JSON Schema `__ | Annotations | 3.5.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 4 | `JSON Schema `__ | Metrics and phases | 3.2.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 3 | `JSON Schema `__ | Project versions | 2.12.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 2 | `JSON Schema `__ | Reply provenance | 2.6.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+ +| 1 | `JSON Schema `__ | Initial versioned metamodel | 2.5.0 | ++-------------------+----------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------+-----------+