Switch to sphinx to be able to translate documentation

We needed to translate in french the Omeka S's documentation, and mkdocs
does not fit our needs. Sphinx provides by default all the tools needed
to translate with PO files and generate translated documentation. The
generated documentation is the same as if it was generated by mkdocs.

Ideally, we think that all the PO files should be in the official
documentation repository, and they could be modified on Transifex, so
that anyone can participate to translation.

Instructions for translating are written inside translation.md

.gitignore

@@ -1,2 +1,4 @@
+_build/
+locales/**/*.mo
 site/
-.DS_Store
+.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)

conf.py

@@ -0,0 +1,64 @@
+# 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'
+
+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 themes produced for Omeka S by RRCHNM have has 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/users.md

@@ -64,7 +64,7 @@ On this tab, create a new password. It must be entered twice, in both the *new p
 
 ![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 Key
 Use this tab to generate an API key for the user. You must provide a label for the key - this could be a date or the purpose of the key. Click save to generate the key.

docs/content/item-sets.md

@@ -127,7 +127,7 @@ By default, Omeka S will use the media from the first item added to an item set
 
 ![Thumbnail tab with no asset selected. The tab displays a message about thumbnail creation and a button to "select" an asset](contentfiles/itemset_thumb1.png)
 
-The assets you select from and upload as thumbnails in this tab are the same as those created for [site logos](../../sites/site_theme/#settings-options). 
+The assets you select from and upload as thumbnails in this tab are the same as those created for [site logos](../sites/site_theme.md#settings-options).
 
 To assign an asset as a thumbnail, click on the Select button in the main work area of the tab. This will open a drawer on the right side. 
 

docs/content/items.md

@@ -207,7 +207,7 @@ By default, Omeka S will use the topmost media to generate a thumbnail for the i
 
 When you use an asset thumbnail instead of uploading media, the asset thumbnail does not display on the item's public show page. This makes such thumbnails useful for items which have no media but which would benefit from a thumbnail for the browse view, or for items whose media does not render an elegant thumbnail, such as audio or visual files.
 
-The assets you select from and upload as thumbnails in this tab are the same as those created for [site logos](../../sites/site_theme/#settings-options). 
+The assets you select from and upload as thumbnails in this tab are the same as those created for [site logos](../sites/site_theme.md#settings-options).
 
 To assign an asset as a thumbnail, click on the Select button in the main work area of the tab. This will open a drawer on the right side. 
 

docs/content/media.md

@@ -32,7 +32,7 @@ Options for navigating and creating items display above the table of items.
 
 On the left side is a display for the number of pages of media, with forward and back arrows. The current page number is an editable field - enter any valid page number and hit return/enter on your keyboard to go to that page. 
 
-In the center top is a button for [Advanced Search](../../search#media-advanced-search). 
+In the center top is a button for [Advanced Search](../search.md#media-advanced-search).
 
 Just above the table on the right are options for sorting media, with two dropdown menus. The first lets you select between *Title*, *Class*, *Owner*, *(date)Created*, and *Size*; the second allows you to sort ascending or descending. To apply, click the *sort* button.
 
@@ -48,7 +48,7 @@ To edit existing media, you can:
 - Go to the Media browse page, click on the title to view the media's metadata and then click the "*Edit media* button in the upper right hand corner
 - Click on the media's name in the right-hand sidebar of an item's page to go to the media's metadata, and then click on *Edit media* from there.
 
-Editing media is very similar to editing [items](../../content/items) or [item sets](../../content/item-sets).
+Editing media is very similar to editing [items](../content/items) or [item sets](../content/item-sets).
 
 ![Edit media page, with no properties loaded](../content/contentfiles/media_edit.png)
 
@@ -151,7 +151,7 @@ In the image below, the first property (Title) is public as indicated by the ope
 
 **Thumbnail** Not all media generate an elegant thumbnail, for example pdf or text file documents or some video files. You can use this option to set a representative thumbnail for the media which will be used on browse pages but not on the page for the item or its media.
 
-The assets you select from and upload as thumbnails in this tab are the same as those created for [site logos](../../sites/site_theme/#settings-options). 
+The assets you select from and upload as thumbnails in this tab are the same as those created for [site logos](../sites/site_theme.md#settings-options).
 
 To assign an asset as a thumbnail, click on the Select button in the main work area of the tab. This will open a drawer on the right side. 
 

docs/frontpage.md

@@ -6,6 +6,6 @@ The page displays all sites which a user has permission to see, along with the s
 
 ![Installation front page for the "Stackable Sandbox" showing seven sites, three of which have summaries.](files/frontpage-basic.png)
 
-If you want this site to be hidden from site visitors, you can use the [setting Default Site](admin/settings/#global-settings) to select a public site on your installation to which visitors will be redirected when they navigate to your base url (`yourdomain.net/omekas/`)
+If you want this site to be hidden from site visitors, you can use the [setting Default Site](admin/settings.md#global-settings) to select a public site on your installation to which visitors will be redirected when they navigate to your base url (`yourdomain.net/omekas/`)
 
-You can use the Default Site option in conjunction with the [site page block](sites/site_pages/#page-blocks) "List of sites" to create a branded site index and to add an about page for the overall installation. 
+You can use the Default Site option in conjunction with the [site page block](sites/site_pages.md#page-blocks) "List of sites" to create a branded site index and to add an about page for the overall installation.

docs/modules/collecting.md

@@ -4,7 +4,7 @@ The Collecting module allows you to gather public contributions through your sit
 
 Once activated on the [modules](index.md) tab of the admin dashboard, Collecting is configured on a site-by-site basis.
 
-### Integrations
+## Integrations
 
 Collecting integrates with the [Custom Vocab](../modules/customvocab/) and the [Numeric data types](../modules/numericdatatypes/) modules.
 

docs/modules/csvimport.md

@@ -134,7 +134,7 @@ This will open a drawer on the right side of the browser window with the followi
 
 - **Use multivalve separator:** check this box to use the multivalue separator for data in this column. You set the multivalue separator in the initial import page, but you can change it in the Basic Settings tab.  
 - **Language:** is a field where you can set the language for this column using the [IETF Language tag](https://en.wikipedia.org/wiki/IETF_language_tag) for the language in which the text is written. This will override what you have entered in basic settings. 
-- **Data type:** is a dropdown with at least three options, which correspond to the [values](../../content/items.md#values) one can use when adding properties to an item:
+- **Data type:** is a dropdown with at least three options, which correspond to the [values](../content/items.md#values) one can use when adding properties to an item:
 	- Import as text (default).
 	- Import as URL reference. You can set the label for the URI by including the desired text after a space, for example:  `http://example.com This Is The Label`
 	- Import as Omeka S resource ID. Note that you must have the correct ID for the resource. A resources' ID is the number sequence at the end of the url when on the view or edit page, so for `/admin/item/11576` the ID is 11576.
@@ -639,7 +639,7 @@ The drawer has a dropdown for Users info, with three options:
 
 - *Email:* the email address for the user;
 - *Display name:* the user's display name
-- *Role:* the user's [role](../../admin/users.md#roles-and-permissions)
+- *Role:* the user's [role](../admin/users.md#roles-and-permissions)
 
 Role values are as follows:
 
@@ -698,7 +698,7 @@ The following are known errors that can occur during an import:
 Some other modules add functionality to CSV import. If you have these modules installed and active, you will have access to the following options when using CSV import.
 
 ### Mapping
-If you have [Mapping](../mapping/) (minimum version 1.1.0) installed and active, you will have two additional options in the "Map to Omeka S data" tab when importing Items. Note that these options do not appear for any other import, including Mixed Resources. 
+If you have [Mapping](mapping) (minimum version 1.1.0) installed and active, you will have two additional options in the "Map to Omeka S data" tab when importing Items. Note that these options do not appear for any other import, including Mixed Resources. 
 
 ![Add mapping drawer with additional options for "Resource location" and "default map view"](../modules/modulesfiles/csvimport_mapping1.png)
 
@@ -717,7 +717,7 @@ If you have [Mapping](../mapping/) (minimum version 1.1.0) installed and active,
 - *Default zoom* should be a number between 1 (most zoomed out) and 18 (most zoomed in)
 
 ### File Sideload
-If you have [File Sideload](../filesideload) (minimum version 1.2.0) installed and active, you can use it as a source for media when running a csv import.
+If you have [File Sideload](filesideload) (minimum version 1.2.0) installed and active, you can use it as a source for media when running a csv import.
 
 Everything on the *Map to Omeka S data* tab will be the same. When you add a mapping and choose the "Media source" option, you will see that there is now an option for "Sideload".
 
@@ -726,6 +726,6 @@ Everything on the *Map to Omeka S data* tab will be the same. When you add a map
 For the data in this column, you need to include the full file name, including extension. So, for example, if you want to import a jpg file which is named "Jekyll_and_Hyde_Title" then the data in the media column of the csv you are importing should be `Jekyll_and_Hyde_Title.jpg`.
 
 ### Numeric Data Types
-If you have [Numeric Data Types](../numericdatatypes) installed and active, it will add the option to set a column data type as numeric data.
+If you have [Numeric Data Types](numericdatatypes) installed and active, it will add the option to set a column data type as numeric data.
 
 ![Column options drawer with the data type dropdown open, showing options for numeric data types as well as the standard options](../modules/modulesfiles/csvimport-numericdata.png)

docs/modules/itemcarouselblock.md

@@ -16,7 +16,7 @@ Attachments may be reordered by dragging and dropping.
 ## Basic Configuration
 The block includes two basic configuration settings. 
 
-![An item carousel block with attached items and configuration settings.](../modules/modulesfiles/itemcarouselblock-basicconfiguration.png)
+![An item carousel block with attached items and configuration settings.](./modulesfiles/itemcarouselblock-basicconfiguration.png)
 
 You may add a title for the carousel.
 
@@ -25,7 +25,7 @@ You can select the number of items that appear on the page at one time. The bloc
 ## Advanced Options
 Using the drop-down menu within the block, you can access a number of advance options to further configure the appearance of the block. 
 
-![An item carousel block detail image focused on the advanced options settings.](../modules/modulesfiles/itemcarouselblock-advancedoptions.png)
+![An item carousel block detail image focused on the advanced options settings.](./modulesfiles/itemcarouselblock-advancedoptions.png)
 
 You can use those settings to: