Switch to sphinx to be able to translate documentation

.gitignore

@@ -1,2 +1,4 @@
+_build/
+locales/**/*.mo
 site/
 .DS_Store

Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -29,8 +29,6 @@ If you are cloning the user manuals to your local computer and creating a branch
 
 **Links** should be composed as relative to the current file. They will look something like `../modules/csvimport.md` if you are linking to a page that sits within a folder, or `../admin/users.md#manage-users` if you are linking to a section of a page. Do not forget the `.md` part of the page.
 
-Links to external websites require the full URL as well as the addition of "{target=_blank}" after the link syntax: for example, `[create a new issue](https://github.com/omeka/omeka-s-enduser/issues){target=_blank}`.
-
 **Images** for a page go into the `files` folder of the directory in which the page sits (so, for "Content" pages, images go into the `contentfiles` directory). Name images clearly, starting with an indicator of the relevant page, and use an underscore to separate out the image's purpose (for example, `items_addItem.png`).
 
 Images should never give information that is not provided in the text (or in the image alt text and title). No one with vision problems should be missing out. Think of images as a shortcut, not the only route, to understanding how to do something. 

_static/js/custom.js

@@ -0,0 +1,3 @@
+$(document).ready(function () {
+    $('a.external').attr('target', '_blank');
+});

conf.py

@@ -0,0 +1,66 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Omeka S end user manual'
+copyright = '2021, Omeka Team'
+author = 'Omeka Team'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'myst_parser'
+]
+
+myst_heading_anchors = 3
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    '_build',
+    'Thumbs.db',
+    '.DS_Store',
+    'README.md',
+    'style-guide.md',
+    'translation.md',
+]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_js_files = ['js/custom.js']
+
+gettext_compact = False

deploy

@@ -1,2 +1,2 @@
-mkdocs build
-rsync -rv --delete site/ /websites/omekaorg/www/s/docs/user-manual
+make clean html
+rsync -rv --delete _build/html /websites/omekaorg/www/s/docs/user-manual

docs/accessibility.rst

@@ -0,0 +1,36 @@
+Accessibility Statement
+=======================
+
+The Omeka team is committed to making Omeka S an accessible option for building
+collections and exhibits online. We are working to make the core code
+accessible and will continue to make accessibility for persons with
+disabilities a priority as we develop the code. Omeka strives to adhere to `W3C
+web design standards <http://www.w3.org/standards/>`_ and to be compliant with
+`Section 508 <http://www.section508.gov/>`_ of the Americans with Disabilities
+Act (pdf).
+
+For more information, please review the following reports:
+
+* Omeka S version 3.x :download:`Accessibility Conformance Report, using VPAT 2.4 Revised International Standards <files/OmekaS3x_ACR.pdf>` (pdf), October 2020.
+* Omeka S version 2.x :download:`Accessibility Conformance Report using VPAT version 2.0 <files/VPAT_OmekaS2-0-1.pdf>` (pdf), August 2019.
+* Omeka S version 1.x :download:`Accessibility Conformance Report using VPAT version 1.1 <files/VPAT2.0-OmekaS1-1.pdf>` (pdf), April 2018.
+
+The following statements apply to Omeka S version 1.0.1 and higher:
+
+Front end (Public view)
+-----------------------
+
+The Omeka S themes produced by the Omeka team have the following features to improve accessibility:
+
+* `ARIA <http://www.w3.org/WAI/intro/aria>`_ (Accessible Rich Internet Applications) landmarks for tabbing through page content, when not using a mouse or using a screen reader.
+* Semantic HTML5 markup.
+
+Please note that although the core code for Omeka S conform to the above standards, installations of Omeka S which have been customized or which are using non-RRCHNM modules and themes may lack some or all of these options. While we encourage developers to consider accessibility, we cannot guarantee that their code includes ARIA Landmarks, SkipNav, or other accessibility considerations.
+
+Back end (Administrative view)
+------------------------------
+
+The administrative dashboard of Omeka S has the following features for accessibility:
+
+*   ARIA landmarks for screen readers on the Admin Dashboard, designating the header, navigation, main content, and footers.
+*   Semantic HTML5 markup.

docs/admin-dashboard.md

@@ -2,7 +2,7 @@
 
 The administrative dashboard manages the content shared by all Omeka S sites and the core functionalities of the Omeka S installation. 
 
-This [screencast](https://vimeo.com/455708039){target=_blank} walks you through the main features of the dashboard and navigating your Omeka S installation:
+This [screencast](https://vimeo.com/455708039) walks you through the main features of the dashboard and navigating your Omeka S installation:
 
 <div style="padding:56.25% 0 0 0;position:relative;"><iframe src="https://player.vimeo.com/video/455708039?h=438143f0d3" style="position:absolute;top:0;left:0;width:100%;height:100%;" frameborder="0" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe></div><script src="https://player.vimeo.com/api/player.js"></script>
 <p><a href="https://vimeo.com/455708039">Navigating Omeka S</a> from <a href="https://vimeo.com/omeka">Omeka</a> on <a href="https://vimeo.com">Vimeo</a>.</p>

docs/admin/settings.md

@@ -29,7 +29,7 @@ Settings are divided into two sections: **General** and **Security** settings.
 
 **Default site**: This dropdown gives you control over where people land when they navigate to the base url of your install. You can either display a list of all sites in the install (default) or select a specific site from the dropdown, to which people will be redirected.
 
-**Locale**: A dropdown that lets you select from a dropdown of [available languages](https://www.transifex.com/omeka/omeka-s/){target=_blank} for the Omeka S core to change the language in which your installation's admin side displays.
+**Locale**: A dropdown that lets you select from a dropdown of [available languages](https://www.transifex.com/omeka/omeka-s/) for the Omeka S core to change the language in which your installation's admin side displays.
 
 **Enable version notifications**: Check this box to enable warning banners for new versions of Omeka S, themes, and modules. If it is unchecked, no user (at any role) will see update warnings, not even the Global Administrator. If it is checked, every applicable user can see them (i.e. Supervisor users who can see the Modules page, Site Managers who can see the Themes pages, and every user on the `/admin` homepage).
 
@@ -39,15 +39,15 @@ Settings are divided into two sections: **General** and **Security** settings.
 
 **Suggested languages for values**: List of languages to facilitate filling of the values in the resource form.
 
-**Media alt text property**: Select a field (for example, `dc:title` or `dc:description`) from the media description to use as alternative text if no alt text is explicitly set. [Alt text](https://webaim.org/techniques/alttext/){target=_blank} is used in lieu of images (including thumbnails on browsing and search results pages) when a user is employing a screen reader and is an important part of meeting accessibility expectations.
+**Media alt text property**: Select a field (for example, `dc:title` or `dc:description`) from the media description to use as alternative text if no alt text is explicitly set. [Alt text](https://webaim.org/techniques/alttext/) is used in lieu of images (including thumbnails on browsing and search results pages) when a user is employing a screen reader and is an important part of meeting accessibility expectations.
 
 **Index full-text search**: Check this box to run an index of your installation's resources and sites as soon as you click "Save". You should only need to run this process if you are having issues with searching.
 
 ## Security
 
 ![Security settings with fields as described below](adminfiles/settings_security.png)
 
-- **Use HTMLPurifier** checkbox. If checked, the service [HTMLPurifier](http://htmlpurifier.org/){target=_blank} will clean up any user-entered HTML. 
+- **Use HTMLPurifier** checkbox. If checked, the service [HTMLPurifier](http://htmlpurifier.org/) will clean up any user-entered HTML. 
 - **Disable file validation**: a checkbox, unchecked by default. When unchecked, file uploads are limited by the following two fields. When this box is checked, any type of media or MIME type can be uploaded.
 - **Allowed media types**: The default list contains the most common media types. Only files with media types included in this list may be uploaded to the installation.
 	- Separate additions to the list with a comma.
@@ -56,7 +56,7 @@ Settings are divided into two sections: **General** and **Security** settings.
 	- Separate additions to the list with a comma.
 	- To return to defaults, click the "Restore default extensions" button.
 
-The final two fields relate to setting up [Google reCAPTCHA](https://www.google.com/recaptcha/intro/index.html){target=_blank} for your site. You will need both a site key and a secret key. Enter them in the corresponding fields after signing up with reCAPTCHA:
+The final two fields relate to setting up [Google reCAPTCHA](https://www.google.com/recaptcha/intro/index.html) for your site. You will need both a site key and a secret key. Enter them in the corresponding fields after signing up with reCAPTCHA:
 
 - **reCAPTCHA site key** enables display of the widget on your install's sites.
 - **reCAPTCHA secret key** allows communication between your install and reCAPTCHA's server. 

docs/admin/users.md

@@ -101,7 +101,7 @@ On this tab, create a new password. It must be entered twice, in both the New Pa
 
 ![Empty password reset fields for the user outreach](adminfiles/users_password.png)
 
-To see the password requirements, click the arrow next to the New Password field. This will display a list of [requirements](../../configuration) if any have been configured.
+To see the password requirements, click the arrow next to the New Password field. This will display a list of [requirements](../configuration) if any have been configured.
 
 ### API keys
 Use this tab to generate an API key for the user. To generate one, you must provide a label for the key - this could be a date or the purpose of the key. Save the page to generate the key.

docs/configuration.md

@@ -2,7 +2,7 @@
 
 The following are commonly requested options which can be configured in the file `local.config.php`, located in the `/config` directory. 
 
-For a full list of available configuration keys, please see the [developer documentation page on configuration settings](https://omeka.org/s/docs/developer/configuration/){target=_blank}. 
+For a full list of available configuration keys, please see the [developer documentation page on configuration settings](https://omeka.org/s/docs/developer/configuration/). 
 
 ## Password settings
 You can change the requirements for user passwords. The options include minimum length, number of upper and lowercase letters, and setting allowed symbols.
@@ -57,9 +57,9 @@ The default thumbnailer is `Omeka\File\Thumbnailer\ImageMagick`. Also available
 
 You can also set the thumbnailer to `Omeka\File\Thumbnailer\NoThumbnail`, which will prevent your Omeka S installation from generating thumbnails. 
 
-[GD](https://secure.php.net/manual/en/intro.image.php){target=_blank} is a basic graphic library installed by default with PHP. It can create thumbnails for common image formats only (jpeg, gif, png). 
+[GD](https://secure.php.net/manual/en/intro.image.php) is a basic graphic library installed by default with PHP. It can create thumbnails for common image formats only (jpeg, gif, png). 
 
-[Imagick and ImageMagick](https://www.imagemagick.org){target=_blank} are the same library and can create thumbnails for more than 200 formats. Imagick is integrated into PHP and ImageMagick is the command-line version. 
+[Imagick and ImageMagick](https://www.imagemagick.org) are the same library and can create thumbnails for more than 200 formats. Imagick is integrated into PHP and ImageMagick is the command-line version. 
 
 ImageMagick may require you to manually set a path in `imagemagick_dir`, whereas Imagick and GD do not require paths.
 
@@ -104,7 +104,7 @@ If you have downloaded the file in order to edit it, be sure to upload the chang
 
 The `mail` key can be used to configure how Omeka S sends emails. Omeka sends emails to users upon registration and when they reset their passwords; modules can add other email functions, such as [confirming submissions](modules/collecting.md). 
 
-The default is to use [sendmail](https://en.wikipedia.org/wiki/Sendmail){target=_blank}, where the server is responsible for having mail delivery configured and set up. Sendmail generally requires no configuration on the Omeka S side. Another option for some servers is to configure a direct SMTP connection for sending mail. 
+The default is to use [sendmail](https://en.wikipedia.org/wiki/Sendmail), where the server is responsible for having mail delivery configured and set up. Sendmail generally requires no configuration on the Omeka S side. Another option for some servers is to configure a direct SMTP connection for sending mail. 
 
 An example configuration, to be added at the end of `local.config.php`, will look something like this:
 
@@ -128,4 +128,4 @@ An example configuration, to be added at the end of `local.config.php`, will loo
     ],
 ```
 
-See the [laminas-mail documentation](https://docs.laminas.dev/laminas-mail/transport/smtp-options/){target=_blank} for clarification.
+See the [laminas-mail documentation](https://docs.laminas.dev/laminas-mail/transport/smtp-options/) for clarification.