Merge branch 'develop' into 7492_muting_notifications IQSS#7492

doc/release-notes/8295-support-postgresql-14.md

@@ -0,0 +1,8 @@
+This release upgrades the bundled PostgreSQL JDBC driver to support major version 14.
+
+Note that the newer PostgreSQL driver required a Flyway version bump, which entails positive and negative consequences:
+
+- The newer version of Flyway supports PostgreSQL 14 and includes a number of security fixes.
+- As of version 8.0 the Flyway Community Edition dropped support for PostgreSQL 9.6 and older.
+
+Upgrade instructions may be found under “PostgreSQL Update” in the 5.10 release notes: https://github.com/IQSS/dataverse/releases/tag/v5.10

doc/sphinx-guides/requirements.txt

@@ -1,4 +1,7 @@
 # current version as of this writing
 Sphinx==3.5.4
 # Necessary workaround for ReadTheDocs for Sphinx 3.x - unnecessary as of Sphinx 4.5+
-Jinja2>=3.0.2,<3.1
+Jinja2>=3.0.2,<3.1
+
+# Sphinx - Additional modules
+sphinx-icon==0.1.2

doc/sphinx-guides/source/_static/docsdataverse_org.css

@@ -60,7 +60,9 @@ ul.navbar-nav li.dropdown.open > span.dropdown-toggle {background: #e7e7e7;}
 }
 
 a.headerlink {
-	display: none;
+    font-size: 60%;
+    vertical-align: middle;
+    color: #d14e6f;
 }
 
 #sidebar.bs-sidenav {

doc/sphinx-guides/source/conf.py

@@ -41,7 +41,8 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
-    'sphinx.ext.graphviz'
+    'sphinx.ext.graphviz',
+    'sphinxcontrib.icon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -239,6 +240,10 @@
 # typographically correct entities.
 #html_use_smartypants = True
 
+# Enable and customize the permanent headerlinks with a nice icon (chain symbol from FontAwesome)
+html_permalinks = True
+html_permalinks_icon = "<i class=\"fas fa-link\"></i>"
+
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 #html_sidebars = {'sidebar': ['localtoc.html', 'sourcelink.html', 'searchbox.html']}

doc/sphinx-guides/source/developers/documentation.rst

@@ -10,15 +10,7 @@ Quick Fix
 
 If you find a typo or a small error in the documentation you can fix it using GitHub's online web editor. Generally speaking, we will be following https://help.github.com/en/articles/editing-files-in-another-users-repository
 
-- Navigate to https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source where you will see folders for each of the guides:
-
-  - `admin`_
-  - `api`_
-  - `developers`_
-  - `installation`_
-  - `style`_
-  - `user`_
-
+- Navigate to https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source where you will see folders for each of the guides: `admin`_, `api`_, `developers`_, `installation`_, `style`_, `user`_.
 - Find the file you want to edit under one of the folders above.
 - Click the pencil icon in the upper-right corner. If this is your first contribution to the Dataverse Project, the hover text over the pencil icon will say "Fork this project and edit this file".
 - Make changes to the file and preview them.
@@ -39,60 +31,59 @@ If you would like to read more about the Dataverse Project's use of GitHub, plea
 .. _style: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/style
 .. _user: https://github.com/IQSS/dataverse/tree/develop/doc/sphinx-guides/source/user
 
-Other Changes (Sphinx)
-----------------------
-
-The documentation for the Dataverse Project was written using Sphinx (http://sphinx-doc.org/). 
-If you are interested in suggesting changes or updates we recommend that you create 
-the html files using Sphinx locally and then submit a pull request through GitHub. Here are the instructions on how to proceed:
+Building the Guides with Sphinx
+-------------------------------
 
+The Dataverse guides are written using Sphinx (http://sphinx-doc.org). We recommend installing Sphinx and building the guides locally so you can get an accurate preview of your changes.
 
 Installing Sphinx
 ~~~~~~~~~~~~~~~~~
 
-On a Mac: 
+First, make a fork of https://github.com/IQSS/dataverse and clone your fork locally. Then change to the ``doc/sphinx-guides`` directory.
 
-Download the sphinx zip file from http://sphinx-doc.org/install.html
+``cd doc/sphinx-guides``
 
-Unzip it somewhere. In the unzipped directory, do the following as
-root, (sudo -i):
+Create a Python virtual environment, activate it, then install dependencies:
 
-python setup.py build
-python setup.py install
+``python3 -m venv venv``
 
-Alternative option (Mac/Unix/Windows):
+``source venv/bin/activate``
 
-Unless you already have it, install pip (https://pip.pypa.io/en/latest/installing.html)
+``pip install -r requirements.txt``
 
-run ``pip install sphinx`` in a terminal
+Installing GraphViz
+~~~~~~~~~~~~~~~~~~~
 
-Building the guides requires the ``dot`` executable from GraphViz and you can find documentation on GraphViz below.
+In some parts of the documentation, graphs are rendered as images using the Sphinx GraphViz extension.
 
-This is all you need. You should now be able to build HTML/pdf documentation from git sources locally.
+Building the guides requires the ``dot`` executable from GraphViz.
 
-Using Sphinx
-~~~~~~~~~~~~
+This requires having `GraphViz <http://graphviz.org>`_ installed and either having ``dot`` on the path or
+`adding options to the make call <https://groups.google.com/forum/#!topic/sphinx-users/yXgNey_0M3I>`_.
 
-First, you will need to make a fork of the Dataverse Software repository in GitHub. Then, you will need to make a clone of your fork so you can manipulate the files outside GitHub.
+Editing and Building the Guides
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To edit the existing documentation:
 
-- Create a branch (refer to http://guides.dataverse.org/en/latest/developers/version-control.html > *Create a New Branch off the develop Branch*) to record the changes you are about to perform.
-- Go to ~/dataverse/doc/sphinx-guides/source directory inside your clone. There, you will find the .rst files that correspond to the guides in the Dataverse Software Guides page (http://guides.dataverse.org/en/latest/).
+- Create a branch (see :ref:`how-to-make-a-pull-request`).
+- In ``doc/sphinx-guides/source`` you will find the .rst files that correspond to http://guides.dataverse.org.
 - Using your preferred text editor, open and edit the necessary files, or create new ones.
 
-**NOTE:** When adding ReStructured Text (RST) `cross references <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_, use the hyphen character (``-``) as the word separator for the cross reference label. For example, ``my-reference-label`` would be the preferred label for a cross reference as opposed to, for example, ``my_reference_label``.
+Once you are done, open a terminal, change directories to ``doc/sphinx-guides``, activate (or reactivate) your Python virtual environment, and build the guides.
 
-Once you are done, open a terminal and change directories to ~/dataverse/doc/sphinx-guides . Then, run the following commands:
+``cd doc/sphinx-guides``
 
-- ``make clean``
+``source venv/bin/activate``
 
-- ``make html``
+``make clean``
 
-After sphinx is done processing the files you should notice that the html folder in ~/dataverse/doc/sphinx-guides/build directory has been updated.
-You can click on the files in the html folder to preview the changes.
+``make html``
 
-Now you can make a commit with the changes to your own fork in GitHub and submit a pull request to the original (upstream) Dataverse Software repository.
+After Sphinx is done processing the files you should notice that the ``html`` folder in ``doc/sphinx-guides/build`` directory has been updated.
+You can click on the files in the ``html`` folder to preview the changes.
+
+Now you can make a commit with the changes to your own fork in GitHub and submit a pull request. See :ref:`how-to-make-a-pull-request`.
 
 Table of Contents
 -----------------
@@ -115,15 +106,10 @@ While PNGs in the git repo can be linked directly via URL, Sphinx-generated imag
 provide higher visual quality. Especially in terms of quality of content, generated images can be extendend and improved
 by a textbased and reviewable commit, without needing raw data or source files and no diff around.
 
-GraphViz based images
-~~~~~~~~~~~~~~~~~~~~~
-
-In some parts of the documentation, graphs are rendered as images via Sphinx GraphViz extension.
+Cross References
+----------------
 
-This requires `GraphViz <http://graphviz.org/>`_ installed and either ``dot`` on the path or
-`adding options to the make call <https://groups.google.com/forum/#!topic/sphinx-users/yXgNey_0M3I>`_.
-
-This has been tested and works on Mac, Linux, and Windows.
+**NOTE:** When adding ReStructured Text (RST) `cross references <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_, use the hyphen character (``-``) as the word separator for the cross reference label. For example, ``my-reference-label`` would be the preferred label for a cross reference as opposed to, for example, ``my_reference_label``.
 
 Versions
 --------

doc/sphinx-guides/source/developers/version-control.rst

@@ -46,6 +46,8 @@ Feature branches are used for both developing features and fixing bugs. They are
 
 "3728-doc-apipolicy-fix" is an example of a fine name for your feature branch. It tells us that you are addressing https://github.com/IQSS/dataverse/issues/3728 and the "slug" is short, descriptive, and starts with the issue number.
 
+.. _how-to-make-a-pull-request:
+
 How to Make a Pull Request
 --------------------------
 

modules/dataverse-parent/pom.xml

@@ -147,7 +147,7 @@
 
         <!-- Major system components and dependencies -->
         <payara.version>5.2021.6</payara.version>
-        <postgresql.version>42.3.3</postgresql.version>
+        <postgresql.version>42.3.5</postgresql.version>
         <solr.version>8.11.1</solr.version>
         <aws.version>1.11.762</aws.version>
         <google.cloud.version>0.157.0</google.cloud.version>

pom.xml

@@ -20,7 +20,7 @@
     <properties>
         <skipUnitTests>false</skipUnitTests>
         <reload4j.version>1.2.18.4</reload4j.version>
-        <flyway.version>5.2.4</flyway.version>
+        <flyway.version>8.5.10</flyway.version>
         <jhove.version>1.20.1</jhove.version>
         <jacoco.version>0.8.7</jacoco.version>
         <poi.version>5.2.1</poi.version>