suggested doc changes for IQSS#7492

- single sorted list of settings - single copy of commands in admin guide - cross link related sections of User and API guide - keep branding images directives together (Oliver was right) - style/consistency tweaks
pdurbin · May 6, 2022 · 450a965 · 450a965
1 parent 4818f79
commit 450a965
Show file tree

Hide file tree

Showing 5 changed files with 49 additions and 78 deletions.
diff --git a/doc/release-notes/7492_muting_notifications.md b/doc/release-notes/7492_muting_notifications.md
@@ -1 +1,7 @@
-This release has a new feature that allows users to control which notifications they receive. How to enable this feature and which options can be set by the admins is described in the [Letting users manage receiving notifications section of the Admin Guide](https://guides.dataverse.org/en/latest/admin/user-administration.html#letting-users-manage-receiving-notifications).
+This release has a new feature that allows users to control which notifications they receive. How to enable this feature and which options can be set by the admins is described in the [Letting users manage receiving notifications section of the Admin Guide](https://guides.dataverse.org/en/latest/admin/user-administration.html#letting-users-manage-receiving-notifications).
+
+## New DB Settings
+
+- :ShowMuteOptions
+- :AlwaysMuted
+- :NeverMuted
diff --git a/doc/sphinx-guides/source/admin/user-administration.rst b/doc/sphinx-guides/source/admin/user-administration.rst
@@ -76,46 +76,49 @@ Using the API token 7ae33670-be21-491d-a244-008149856437 as an example:
 
 You should expect the output ``DELETE 1`` after issuing the command above.
 
+.. _mute-notifications:
 
-Letting users manage receiving notifications
---------------------------------------------
+Letting Users Manage Notifications
+-----------------------------------
 
-You can let users manage which notification types they wish to receive by using the following setting:
+See :ref:`account-notifications` in the User Guide for how notifications are described to end users.
+
+You can let users manage which notification types they wish to receive by setting :ref:`:ShowMuteOptions` to "true":
 
 ``curl -X PUT -d 'true' http://localhost:8080/api/admin/settings/:ShowMuteOptions``
 
-This enables the new feature in the notifications page. The users can then select which in-app notifications and/or e-mails they wish to receive out of the following list:
+This enables additional settings for each user in the notifications tab of their account page. The users can select which in-app notifications and/or e-mails they wish to receive out of the following list:
 
+* ``APIGENERATED`` API token is generated
 * ``ASSIGNROLE`` Role is assigned
-* ``REVOKEROLE`` Role is revoked
-* ``CREATEDV`` Dataverse is created
-* ``CREATEDS`` Your dataset is created
-* ``CREATEACC`` Account is created
-* ``SUBMITTEDDS`` Submitted for review
-* ``RETURNEDDS`` Returned from review
-* ``PUBLISHEDDS`` Dataset is published
-* ``REQUESTFILEACCESS`` Access to file is requested
-* ``GRANTFILEACCESS`` Access to file is granted
-* ``REJECTFILEACCESS`` Access to file is rejected
-* ``FILESYSTEMIMPORT`` Dataset has been successfully uploaded and verified
-* ``CHECKSUMIMPORT`` Dataset had file checksums added via a batch job
 * ``CHECKSUMFAIL`` Checksum validation failed
+* ``CHECKSUMIMPORT`` Dataset had file checksums added via a batch job
 * ``CONFIRMEMAIL`` Email Verification
-* ``APIGENERATED`` API token is generated
-* ``INGESTCOMPLETED`` Ingest is completed
+* ``CREATEACC`` Account is created
+* ``CREATEDS`` Your dataset is created
+* ``CREATEDV`` Dataverse is created
+* ``DATASETCREATED`` Dataset was created by user
+* ``FILESYSTEMIMPORT`` Dataset has been successfully uploaded and verified
+* ``GRANTFILEACCESS`` Access to file is granted
 * ``INGESTCOMPLETEDWITHERRORS`` Ingest completed with errors
+* ``INGESTCOMPLETED`` Ingest is completed
+* ``PUBLISHEDDS`` Dataset is published
 * ``PUBLISHFAILED_PIDREG`` Publish has failed
-* ``WORKFLOW_SUCCESS`` External workflow run has succeeded
-* ``WORKFLOW_FAILURE`` External workflow run has failed
+* ``REJECTFILEACCESS`` Access to file is rejected
+* ``REQUESTFILEACCESS`` Access to file is requested
+* ``RETURNEDDS`` Returned from review
+* ``REVOKEROLE`` Role is revoked
 * ``STATUSUPDATED`` Status of dataset has been updated
-* ``DATASETCREATED`` Dataset was created by user
+* ``SUBMITTEDDS`` Submitted for review
+* ``WORKFLOW_FAILURE`` External workflow run has failed
+* ``WORKFLOW_SUCCESS`` External workflow run has succeeded
 
 After enabling this feature, all notifications are enabled by default, until this is changed by the user.
 
-You can then shorten this list by configuring some notification types (e.g., ``ASSIGNROLE`` and ``REVOKEROLE``) to be always muted for everyone and not manageable by users (not visible in the user interface) with the following setting:
+You can shorten this list by configuring some notification types (e.g., ``ASSIGNROLE`` and ``REVOKEROLE``) to be always muted for everyone and not manageable by users (not visible in the user interface) with the :ref:`:AlwaysMuted` setting:
 
 ``curl -X PUT -d 'ASSIGNROLE,REVOKEROLE' http://localhost:8080/api/admin/settings/:AlwaysMuted``
 
-Finally, you can set some notifications (e.g., ``REQUESTFILEACCESS``, ``GRANTFILEACCESS`` and ``REJECTFILEACCESS``) as always enabled for everyone and not manageable by users (grayed out in the user interface) with the following setting:
+Finally, you can set some notifications (e.g., ``REQUESTFILEACCESS``, ``GRANTFILEACCESS`` and ``REJECTFILEACCESS``) as always enabled for everyone and not manageable by users (grayed out in the user interface) with the :ref:`:NeverMuted` setting:
 
 ``curl -X PUT -d 'REQUESTFILEACCESS,GRANTFILEACCESS,REJECTFILEACCESS' http://localhost:8080/api/admin/settings/:NeverMuted``
diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst
@@ -2836,6 +2836,8 @@ Show Info About Single Metadata Block
 Notifications
 -------------
 
+See also :ref:`account-notifications` in the User Guide.
+
 Get All Notifications by User
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/doc/sphinx-guides/source/installation/config.rst b/doc/sphinx-guides/source/installation/config.rst
@@ -657,6 +657,10 @@ The image below indicates that the page layout consists of three main blocks: a
 
 |dvPageBlocks|
 
+.. To edit, use dvBrandingCustBlocks.drawio with https://app.diagrams.net
+.. |dvPageBlocks| image:: ./img/dvBrandingCustBlocks.png
+   :class: img-responsive
+
 Installation Name/Brand Name
 ++++++++++++++++++++++++++++
 
@@ -2719,75 +2723,29 @@ To remove the override and go back to the default list:
 
 ``curl -X PUT -d '' http://localhost:8080/api/admin/settings/:FileCategories``
 
+.. _:ShowMuteOptions:
+
 :ShowMuteOptions
 ++++++++++++++++
 
 Enables muting of the notifications by the users. By default, this setting is "false" and users cannot mute any notifications (this feature is not shown in the user interface).
 
-This setting is a boolean value. To turn the feature on:
-
-``curl -X PUT -d 'true' http://localhost:8080/api/admin/settings/:ShowMuteOptions``
-
-To remove the override and turn this feature off:
-
-``curl -X PUT -d 'false' http://localhost:8080/api/admin/settings/:ShowMuteOptions``
-
-The existing notification types are as follows:
-* ``ASSIGNROLE`` Role is assigned
-* ``REVOKEROLE`` Role is revoked
-* ``CREATEDV`` Dataverse is created
-* ``CREATEDS`` Your dataset is created
-* ``CREATEACC`` Account is created
-* ``SUBMITTEDDS`` Submitted for review
-* ``RETURNEDDS`` Returned from review
-* ``PUBLISHEDDS`` Dataset is published
-* ``REQUESTFILEACCESS`` Access to file is requested
-* ``GRANTFILEACCESS`` Access to file is granted
-* ``REJECTFILEACCESS`` Access to file is rejected
-* ``FILESYSTEMIMPORT`` Dataset has been successfully uploaded and verified
-* ``CHECKSUMIMPORT`` Dataset had file checksums added via a batch job
-* ``CHECKSUMFAIL`` Checksum validation failed
-* ``CONFIRMEMAIL`` Email Verification
-* ``APIGENERATED`` API token is generated
-* ``INGESTCOMPLETED`` Ingest is completed
-* ``INGESTCOMPLETEDWITHERRORS`` Ingest completed with errors
-* ``PUBLISHFAILED_PIDREG`` Publish has failed
-* ``WORKFLOW_SUCCESS`` External workflow run has succeeded
-* ``WORKFLOW_FAILURE`` External workflow run has failed
-* ``STATUSUPDATED`` Status of dataset has been updated
-* ``DATASETCREATED`` Dataset was created by user
+For configuration details, see :ref:`mute-notifications`.
+
+.. _:AlwaysMuted:
 
 :AlwaysMuted
 ++++++++++++
 
 Overrides the default empty list of always muted notifications. Always muted notifications cannot be unmuted by the users. Always muted notifications are not shown in the notification settings for the users.
 
-This setting is a comma-separated list of the notification types.
-
-To override the default empty list with ASSIGNROLE, REVOKEROLE:
-
-``curl -X PUT -d 'ASSIGNROLE,REVOKEROLE' http://localhost:8080/api/admin/settings/:AlwaysMuted``
-
-To remove the override and go back to the empty list:
+For configuration details, see :ref:`mute-notifications`.
 
-``curl -X PUT -d '' http://localhost:8080/api/admin/settings/:AlwaysMuted``
+.. _:NeverMuted:
 
 :NeverMuted
 +++++++++++
 
 Overrides the default empty list of never muted notifications. Never muted notifications cannot be muted by the users. Always muted notifications are grayed out and are not adjustable by the user.
 
-This setting is a comma-separated list of the notification types.
-
-To override the default empty list with REQUESTFILEACCESS, GRANTFILEACCESS, REJECTFILEACCESS:
-
-``curl -X PUT -d 'REQUESTFILEACCESS,GRANTFILEACCESS,REJECTFILEACCESS' http://localhost:8080/api/admin/settings/:NeverMuted``
-
-To remove the override and go back to the empty list:
-
-``curl -X PUT -d '' http://localhost:8080/api/admin/settings/:NeverMuted``
-
-.. To edit, use dvBrandingCustBlocks.drawio with https://app.diagrams.net
-.. |dvPageBlocks| image:: ./img/dvBrandingCustBlocks.png
-   :class: img-responsive
-
+For configuration details, see :ref:`mute-notifications`.
diff --git a/doc/sphinx-guides/source/user/account.rst b/doc/sphinx-guides/source/user/account.rst
@@ -155,6 +155,8 @@ The My Data section of your account page displays a listing of all the Dataverse
 
 You can use the Add Data button to create a new Dataverse collection or dataset. By default, the new Dataverse collection or dataset will be created in the root Dataverse collection, but from the create form you can use the Host Dataverse collection dropdown menu to choose a different Dataverse collection, for which you have the proper access privileges. However, you will not be able to change this selection after you create your Dataverse collection or dataset.
 
+.. _account-notifications:
+
 Notifications
 -------------