From 425127d2adf93000aa641af6cf64018b2b2f47ef Mon Sep 17 00:00:00 2001 From: Julian Maurice Date: Mon, 28 Jun 2021 08:40:24 +0000 Subject: [PATCH] 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 | 4 +- Makefile | 20 +++++ _docmap.md | 18 ----- conf.py | 64 +++++++++++++++ deploy | 4 +- docs/accessibility.md | 26 ------ docs/accessibility.rst | 36 +++++++++ docs/admin/users.md | 2 +- docs/content/item-sets.md | 2 +- docs/content/items.md | 2 +- docs/content/media.md | 6 +- docs/frontpage.md | 4 +- docs/index.md | 23 ------ docs/modules/collecting.md | 2 +- docs/modules/csvimport.md | 14 ++-- docs/modules/itemcarouselblock.md | 4 +- docs/modules/mapping.md | 8 +- docs/modules/metadatabrowse.md | 4 +- docs/modules/numericdatatypes.md | 2 +- docs/modules/scripto.rst | 9 +++ docs/modules/scripto/index.md | 2 +- docs/modules/scripto/scriptoPublicView.md | 10 +-- docs/modules/scripto/scriptoproject.md | 4 +- docs/s-planning-tips.md | 14 ++-- docs/search.md | 18 ++--- docs/sites/index.md | 2 +- docs/sites/site_navigation.md | 2 +- docs/sites/site_pages.md | 4 +- docs/sites/site_settings.md | 6 +- docs/sites/site_theme.md | 2 +- index.rst | 97 +++++++++++++++++++++++ make.bat | 35 ++++++++ mkdocs.yml | 68 ---------------- requirements.txt | 5 ++ translation.md | 13 +++ 35 files changed, 341 insertions(+), 195 deletions(-) create mode 100644 Makefile delete mode 100644 _docmap.md create mode 100644 conf.py delete mode 100644 docs/accessibility.md create mode 100644 docs/accessibility.rst delete mode 100644 docs/index.md create mode 100644 docs/modules/scripto.rst create mode 100644 index.rst create mode 100644 make.bat delete mode 100644 mkdocs.yml create mode 100644 requirements.txt create mode 100644 translation.md diff --git a/.gitignore b/.gitignore index 0efad7bb..058d5560 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ +_build/ +locales/**/*.mo site/ -.DS_Store \ No newline at end of file +.DS_Store diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/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) diff --git a/_docmap.md b/_docmap.md deleted file mode 100644 index bc7b3274..00000000 --- a/_docmap.md +++ /dev/null @@ -1,18 +0,0 @@ -Documentation Map - -- admin dashboard -- glossary -- settings -- users -- content: - - items - - item sets - - media - - resource templates - - vocabularies -- sites - - sites management - - pages management -- modules - - modules (managing) - - individual modules documentation \ No newline at end of file diff --git a/conf.py b/conf.py new file mode 100644 index 00000000..b1f71f14 --- /dev/null +++ b/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 diff --git a/deploy b/deploy index bf696816..27ef216e 100644 --- a/deploy +++ b/deploy @@ -1,2 +1,2 @@ -mkdocs build -rsync -rv --delete site/ /websites/omekaorg/www/s/docs/user-manual \ No newline at end of file +make clean html +rsync -rv --delete _build/html /websites/omekaorg/www/s/docs/user-manual diff --git a/docs/accessibility.md b/docs/accessibility.md deleted file mode 100644 index 4c53a404..00000000 --- a/docs/accessibility.md +++ /dev/null @@ -1,26 +0,0 @@ -# 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 [Accessibility Conformance Report, using VPAT 2.4 Revised International Standards](files/OmekaS3x_ACR.pdf) (pdf), October 2020. -- Omeka S version 2.x [Accessibility Conformance Report using VPAT version 2.0](files/VPAT_OmekaS2-0-1.pdf) (pdf), August 2019. -- Omeka S version 1.x [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. diff --git a/docs/accessibility.rst b/docs/accessibility.rst new file mode 100644 index 00000000..7af5c06e --- /dev/null +++ b/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 `_ and to be compliant with +`Section 508 `_ 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 ` (pdf), October 2020. +* Omeka S version 2.x :download:`Accessibility Conformance Report using VPAT version 2.0 ` (pdf), August 2019. +* Omeka S version 1.x :download:`Accessibility Conformance Report using VPAT version 1.1 ` (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 `_ (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. diff --git a/docs/admin/users.md b/docs/admin/users.md index 34cc9822..b36fe8d3 100644 --- a/docs/admin/users.md +++ b/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. diff --git a/docs/content/item-sets.md b/docs/content/item-sets.md index 366b3680..7c7b6f30 100644 --- a/docs/content/item-sets.md +++ b/docs/content/item-sets.md @@ -102,7 +102,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. diff --git a/docs/content/items.md b/docs/content/items.md index 4e44c47e..f5d935f2 100644 --- a/docs/content/items.md +++ b/docs/content/items.md @@ -183,7 +183,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. diff --git a/docs/content/media.md b/docs/content/media.md index b31ee991..5c273b12 100644 --- a/docs/content/media.md +++ b/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) @@ -125,7 +125,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. diff --git a/docs/frontpage.md b/docs/frontpage.md index b8cc38c2..a86fd45b 100644 --- a/docs/frontpage.md +++ b/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. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 75e79516..00000000 --- a/docs/index.md +++ /dev/null @@ -1,23 +0,0 @@ -# Omeka S User Manual - -Omeka S is a web publication system for universities, galleries, libraries, archives, and museums. It creates a local network of independently curated exhibits sharing a collaboratively built pool of items and their metadata. - -The sections of this manual correspond to the navigation sections on the left-hand side of the [administrative dashboard](admin-dashboard.md) of an Omeka S Installation: - -**Sites** -Creating, editing, and managing sites, the public-facing parts of an Omeka S installation. - -**Resources** -Creating, editing, and managing the content of an installation: items, item sets, media, vocabularies, and resource templates. - -**Admin** -Access to functionality in the admin section varies by user role, but can include: users, jobs, and settings. - -**Modules** -This section opens with basic information on managing the modules which extend the functionality of your Omeka S installation and sites. It then offers specific documentaiton for Omeka S modules created by RRCHNM, listed in alphabetial order. - -This manual also includes a [glossary](glossary.md), instructions on conducting [searches](search.md), and how to turn on [error logging](errorLogging.md). - -Screencasts to supplement the documentation are linked from relevant pages, and can be browsed in the [Omeka S collection on Vimeo](https://vimeo.com/showcase/4215056). - -This documentation is CC-BY-NC diff --git a/docs/modules/collecting.md b/docs/modules/collecting.md index cd92724a..8d265c97 100644 --- a/docs/modules/collecting.md +++ b/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. diff --git a/docs/modules/csvimport.md b/docs/modules/csvimport.md index c9b3481e..c274430e 100644 --- a/docs/modules/csvimport.md +++ b/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/#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. @@ -262,7 +262,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/#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. @@ -401,7 +401,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/#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. @@ -545,7 +545,7 @@ This will open a drawer on the right side of the browser window with the followi - **Use multivalue separator:** check this box to use the multivalue separator for data in this column. You set the multivalue separator character 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/#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. @@ -638,7 +638,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/#roles-and-permissions) - for this column, use the role labels exactly as they appear in Omeka S. +- *Role:* the user's [role](../admin/users.md#roles-and-permissions) - for this column, use the role labels exactly as they appear in Omeka S. ![The same table as above, now with the mapping drawer open and the dropdown activated to show the three options.](../modules/modulesfiles/csvimport_usersMap.png) @@ -706,7 +706,7 @@ If you have [Mapping](../modules/mapping/) (minimum version 1.1.0) installed and - *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" @@ -715,6 +715,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](modules/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) diff --git a/docs/modules/itemcarouselblock.md b/docs/modules/itemcarouselblock.md index 3a720b00..e4cb3d9d 100644 --- a/docs/modules/itemcarouselblock.md +++ b/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: diff --git a/docs/modules/mapping.md b/docs/modules/mapping.md index 79d154b3..2d063ca3 100644 --- a/docs/modules/mapping.md +++ b/docs/modules/mapping.md @@ -49,7 +49,7 @@ You can now click on the marker to add a label which will display on [public map ![Close up of map with a marker selected. There is a field to enter the maker label.](../modules/modulesfiles/Mapping-addLabel.png) -When you are adding a label, you can also add an image to display on the marker when clicked in the [public view](../modules/mapping/#public-view). You can only select from images which has already been [attached to the item as media](../content/items/#media). To remove the image, select "no Image" from the sidebar. +When you are adding a label, you can also add an image to display on the marker when clicked in the [public view](#public-view). You can only select from images which has already been [attached to the item as media](../content/items.md#media). To remove the image, select "no Image" from the sidebar. ![Marker selected with Image added. The media is also visible in the sidebar, along with an option for "no image"](../modules/modulesfiles/Mapping-addImage.png) @@ -120,10 +120,10 @@ Within the preview map, there are five buttons: ![Screenshot of the WMS Overlays with empty fields and the US and Territories overlay above the fields. A blue arrow points to the overlay](../modules/modulesfiles/Mapping_Page_Overlays2.png) ### Timeline -Timeline adds a timeline display to the left of the map view. Note that this feature requires the [NumericDataTypes](../modules/numericdatatypes/) module and at least one item that has a property with a Timestamp or Interval value (applied via the [resource template](../../content/resource-template/)). +Timeline adds a timeline display to the left of the map view. Note that this feature requires the [NumericDataTypes](../modules/numericdatatypes/) module and at least one item that has a property with a Timestamp or Interval value (applied via the [resource template](../content/resource-template)). -- *Title headline:* displays on the first slide of the timeline (see ["Timeline public view"](../../modules/mapping/#timeline-public-view) below). You can use this to name the timeline. -- *Title text:* appears below the title headline on the first slide of the timeline (see ["Timeline public view"](../../modules/mapping/#timeline-public-view) below). You can use this to provide context or narrative introduction for the timeline. +- *Title headline:* displays on the first slide of the timeline (see ["Timeline public view"](#timeline-public-view) below). You can use this to name the timeline. +- *Title text:* appears below the title headline on the first slide of the timeline (see ["Timeline public view"](#timeline-public-view) below). You can use this to provide context or narrative introduction for the timeline. - *Fly to:* is a dropdown menu where you can set the zoom level for each point in the timeline on the map. Your options are default view, or zoom levels 0-18 (even numbers only). The higher the number, the more zoomed in the map will be. - Note that the transition between points is animated, so if you have very distant points the shift between them will involve a significant zoom out and in. - *Show contemporaneous events:* sets how two events with the same timestamp or interval are displayed. If checked, contemporaneous events will both display in the map when active in the story slider. diff --git a/docs/modules/metadatabrowse.md b/docs/modules/metadatabrowse.md index 70678808..7e22b82f 100644 --- a/docs/modules/metadatabrowse.md +++ b/docs/modules/metadatabrowse.md @@ -50,7 +50,7 @@ To remove a property simply click the trash can/delete icon to the right of the Once you have selected properties for Metadata Browse, either in the configuration for the module or on at least one site, you will be able to search for exact matches to item and item set properties on the admin side. -When viewing the metadata of any item (not when editing), you will be able to browse those properties as exact match for any other item in the installation with that value in that property. If the direct [direct link checkbox](#direct-links) is active, these properties will display as links; if not, they will display with the text "see all items with this value" just below the value for the property. +When viewing the metadata of any item (not when editing), you will be able to browse those properties as exact match for any other item in the installation with that value in that property. If the direct [direct link checkbox](#direct-links-checkbox) is active, these properties will display as links; if not, they will display with the text "see all items with this value" just below the value for the property. ![Admin side view of item with red arrows pointing to the metadata browse links](../modules/modulesfiles/mdbr_admin1.png) @@ -75,7 +75,7 @@ Remember to click the *Save* button to save changes. ### Public View Once you have selected properties and saved changes, visitors to your site can use the Metadata Browse properties to search for all items on the site with matching properties. -The browse will either display with the property as a link or with the link text "see all items with this value", depending on whether the [direct link checkbox](#direct-links) in the global module configuration. +The browse will either display with the property as a link or with the link text "see all items with this value", depending on whether the [direct link checkbox](#direct-links-checkbox) in the global module configuration. In the example below, Metadata Browse is available for Title, Date of Publication, and Publisher, and Direct Links is not active. diff --git a/docs/modules/numericdatatypes.md b/docs/modules/numericdatatypes.md index 2b81cb80..dac3220a 100644 --- a/docs/modules/numericdatatypes.md +++ b/docs/modules/numericdatatypes.md @@ -84,7 +84,7 @@ Clicking on this dropdown will reveal multiple options, including all of the pro ## Bulk edit numeric data -The module adds an additional option to the [item batch edit](../../content/items/#batch-editing): convert to numeric. +The module adds an additional option to the [item batch edit](../content/items.md#batch-actions): convert to numeric. ![Batch edit items form with a red rectangle outline surrounding the convert to numeric option](../modules/modulesfiles/ndt-batchoption diff --git a/docs/modules/scripto.rst b/docs/modules/scripto.rst new file mode 100644 index 00000000..7a8f82f2 --- /dev/null +++ b/docs/modules/scripto.rst @@ -0,0 +1,9 @@ +========= + Scripto +========= + +.. toctree:: + :glob: + :maxdepth: 2 + + scripto/* diff --git a/docs/modules/scripto/index.md b/docs/modules/scripto/index.md index c8895ee6..d67e7a56 100644 --- a/docs/modules/scripto/index.md +++ b/docs/modules/scripto/index.md @@ -22,7 +22,7 @@ To install Scripto, you must: - be running Omeka S v2.0.0 or higher; - have a [MediaWiki](https://www.mediawiki.org/wiki/MediaWiki) installation running on the same server as the Omeka S installation. Minimum MediaWiki version is 1.30.0. -Create the MediaWiki installation on your server using [their instructions](https://www.mediawiki.org/wiki/Manual:FAQ#Installation_and_configuration). Install the Scripto module using the [documentation for installing modules](../../modules/#installing-modules). +Create the MediaWiki installation on your server using [their instructions](https://www.mediawiki.org/wiki/Manual:FAQ#Installation_and_configuration). Install the Scripto module using the [documentation for installing modules](../index.md#installing-modules). Once you have installed the module and created your MediaWiki installation, go to the Modules tab of your Omeka S installation and activate the Scripto module. diff --git a/docs/modules/scripto/scriptoPublicView.md b/docs/modules/scripto/scriptoPublicView.md index 5b6982a2..74a055a3 100644 --- a/docs/modules/scripto/scriptoPublicView.md +++ b/docs/modules/scripto/scriptoPublicView.md @@ -13,12 +13,12 @@ For an example of how to orient community members to the interface, see the [Gui ## Linking between Scripto and an Omeka S site While the Scripto public interface exists somewhat separately from the sites you build in your Omeka S installation, it is possible to move between them. -From your Omeka S sites, you can create direct links to your Scripto projects using the [custom link](../../../sites/site_navigation/#custom-link) in site Navigation or as a link in any [HTML page block text](../../../sites/site_pages/#html). +From your Omeka S sites, you can create direct links to your Scripto projects using the [custom link](../../sites/site_navigation.md#add-a-custom-link) in site Navigation or as a link in any [HTML page block text](../../sites/site_pages.md#html). ### Scripto page block -When you add the Scripto module, it creates a new [page block](../../../sites/site_pages/#page-blocks) called "Scripto" +When you add the Scripto module, it creates a new [page block](../../sites/site_pages.md#page-blocks) called "Scripto" -The Scripto page block offers a drop-down to let you select from all available Scripto [projects](../scriptoproject/). Select the project you want to link from the dropdown. +The Scripto page block offers a drop-down to let you select from all available Scripto [projects](scriptoproject). Select the project you want to link from the dropdown. ![Dropdown with a single site option](../modulesfiles/scripto-pageBlock.png) @@ -56,7 +56,7 @@ The list of watched pages displays the following information: ## Public project browse On the upper right of the browser, near the "Log In" buttons or, when logged in, the user icon, is a link to browse all projects in the Scripto instance. -This browse page shows the project title, a representative icon determined by the first item in the project, and the project's description (set in the [configuration options](../scriptoproject/#configuration-options)), if any. +This browse page shows the project title, a representative icon determined by the first item in the project, and the project's description (set in the [configuration options](scriptoproject.md#configuration-options)), if any. ![Project browse showing three projects, only two of which have a description.](../../modules/modulesfiles/scripto-publicBrowse.png) Clicking on any project's title or representative thumbnail takes you to the project's view. @@ -71,7 +71,7 @@ Across the top of the page, just under the Scripto navigation options (project b - a browse items links; and - a search bar to search the items in the project (this is a full-text search for the metadata of the items and media). -Below this is a table of the items in the project. The table will be labeled Items unless you selected from the Item type dropdown in the project's [configuration options](../scriptoproject/#configuration-options). +Below this is a table of the items in the project. The table will be labeled Items unless you selected from the Item type dropdown in the project's [configuration options](scriptoproject.md#configuration-options). The table has two display options. The default view is set in the project's configuration options. diff --git a/docs/modules/scripto/scriptoproject.md b/docs/modules/scripto/scriptoproject.md index 07f18b6d..ee5abda3 100644 --- a/docs/modules/scripto/scriptoproject.md +++ b/docs/modules/scripto/scriptoproject.md @@ -78,7 +78,7 @@ If you select Media, the content created in Scripto will appear in the media met - Translation ### Reviewers -Add [Omeka S users](../../../admin/users/) to your Scripto project as reviewers, who can can access private projects, and mark media as approved and unapproved. You can manage users after adding a project (see below) +Add [Omeka S users](../../admin/users) to your Scripto project as reviewers, who can can access private projects, and mark media as approved and unapproved. You can manage users after adding a project (see below) Only Omeka users with **site administrator** and g**lobal administrator** roles can sync and import projects, due to the destructive potential of those actions. @@ -251,7 +251,7 @@ The next section is **Review status**. You can toggle the drawer open and closed using the open arrow `>` button in the middle of the divider between the drawer and the main work area. -#### Media status: +### Media status: * **Complete:** Community users have the ability to mark a media they are working on as "complete." This serves as a flag to notify the project team that the media is ready for review. If a media is not completely transcribed/translated/described, adminstrators can reverse the Complete status. * **Approved:** Approval is granted by administrators and indicates that every media is complete and satisfactory. Items can only be considered approved when all child media are approved. diff --git a/docs/s-planning-tips.md b/docs/s-planning-tips.md index 63406218..3dd55f49 100644 --- a/docs/s-planning-tips.md +++ b/docs/s-planning-tips.md @@ -1,6 +1,6 @@ # Planning Tips -In Omeka S, you build your [sites](../sites) page by page, using already existing resources on your installation. While it is best to have some resources before you start building out the pages, you can begin planning your site before you create the first item or item set. +In Omeka S, you build your [sites](sites/index) page by page, using already existing resources on your installation. While it is best to have some resources before you start building out the pages, you can begin planning your site before you create the first item or item set. What follows are some questions and ideas to help guide you as you plan your sites in Omeka S. @@ -13,25 +13,25 @@ What follows are some questions and ideas to help guide you as you plan your sit ## Resources **What will you do with items in this website?** -[Items](../content/items/) are the building blocks of Omeka S. What sort of [resource templates](../content/resource-template/) will you want to create and use to fully describe your items? Any item you include on an Omeka S will have a public item show page, so try to ensure that the information in an item's metadata can stand on its own. +[Items](content/items) are the building blocks of Omeka S. What sort of [resource templates](content/resource-template) will you want to create and use to fully describe your items? Any item you include on an Omeka S will have a public item show page, so try to ensure that the information in an item's metadata can stand on its own. **What will you do with item sets?** -You can use [item sets](../content/item-sets) to group items to be included on a [site](../sites), and they can be a way to guide visitors' browsing on your sites. For some sites, item sets are robust resources themselves. +You can use [item sets](content/item-sets) to group items to be included on a [site](sites/index), and they can be a way to guide visitors' browsing on your sites. For some sites, item sets are robust resources themselves. How do you want to group items into sets? What metadata fields will your item sets use? Do your item sets have relations to each other or to items? **What do you want your data to do?** -What properties are you going to want to consistently describe in your site? Do you want some of these to display with a different label - for example 'author' instead of 'creator' for books? Use a [resource template](../content/resource-template/) and change the label of the property. +What properties are you going to want to consistently describe in your site? Do you want some of these to display with a different label - for example 'author' instead of 'creator' for books? Use a [resource template](content/resource-template) and change the label of the property. In Omeka S, items and item sets can use other resources - items, item sets, and media - as properties; for example, you can make an item for William Shakespeare and have that item fill the 'creator' property for a 'Hamlet' item. How can your resources use this functionality? -Do you want to use a set of terms (controlled vocabulary) for certain items? You might want to use [Custom Vocab](../modules/customvocab/). Or do you want to use a terms list created by the Library of Congress or the Getty? Then you might use [Vocab Suggest](../modules/valuesuggest/). +Do you want to use a set of terms (controlled vocabulary) for certain items? You might want to use [Custom Vocab](modules/customvocab). Or do you want to use a terms list created by the Library of Congress or the Getty? Then you might use [Vocab Suggest](modules/valuesuggest). ## Building a site With Omeka S you will build your site from the ground up, which means you need to give some thought to how you want to organize your site. What pages do you want to include? What kind of content do you want on these pages? How do you want to arrange them? Try sketching out a sample menu or wireframes for the site. Use that as a guide as you build your pages. -Pages are made up of [blocks](../sites/site_pages/#page-blocks), which can include text, images, and much more. What kind of content do you want on the pages you build? Bear in mind that you can rearrange page blocks as you build, so you can play around with the order of the content on your pages if you need to. +Pages are made up of [blocks](sites/site_pages.md#page-blocks), which can include text, images, and much more. What kind of content do you want on the pages you build? Bear in mind that you can rearrange page blocks as you build, so you can play around with the order of the content on your pages if you need to. -How do you want to interact with your visitors on your site? Do you want to [collect](../modules/collecting/) resources from your visitors? Allow them to [share](../modules/sharing/) your content on social media? +How do you want to interact with your visitors on your site? Do you want to [collect](modules/collecting) resources from your visitors? Allow them to [share](modules/sharing) your content on social media? diff --git a/docs/search.md b/docs/search.md index ce0b39b6..21c4cb2b 100644 --- a/docs/search.md +++ b/docs/search.md @@ -16,7 +16,7 @@ By default, this search operates on items in your installation. However, you can ### Item advanced search -Advanced search for items only is available on the [Items](/content/items.md) page, from the *Advanced Search* link above the table of items. +Advanced search for items only is available on the [Items](content/items) page, from the *Advanced Search* link above the table of items. ![Advanced search button indicated with a red arrow.](files/advancedsearch2.png) @@ -59,7 +59,7 @@ You can remove value and item set searches using the red trash can icon to the r You can reset your search terms at any time by using the "Reset" button on the upper right next to the "Search" button. ## Media advanced search -Advanced search for media is accessed from the [Media](/content/media) browse page, from the *Advanced Search* link above the table of item sets. +Advanced search for media is accessed from the [Media](content/media) browse page, from the *Advanced Search* link above the table of item sets. ![Advanced search button indicated with a red arrow.](files/search_mediaadvance1.png) @@ -91,7 +91,7 @@ You can remove value searches using the red trash can icon to the right of the v *Search by MIME type:* you can specify the media type for the search. For example, to find all tiff images, you would enter `image/tiff`. -![Advanced media search options form, with fields as described above.](/files/search_mediaadvance2.png) +![Advanced media search options form, with fields as described above.](files/search_mediaadvance2.png) Searches by value, class, and template allow you to search by more than one input - use the *add new* buttons to search with more than one value or item set. These search terms build - searching for two templates will return all media using either template. @@ -103,7 +103,7 @@ You can reset your search terms at any time by using the "Reset" button on the u Advanced search for item sets only is accessed on the [Item Sets](content/item-sets) page, from the *Advanced Search* link above the table of item sets. -![Advanced search button indicated with a red arrow.](/files/advancedsearchis1.png) +![Advanced search button indicated with a red arrow.](files/advancedsearchis1.png) The advanced search loads on a new page, and has the following options: @@ -138,7 +138,7 @@ Searches by value, class, and template allow you to search by more than one inpu You can reset your search terms at any time by using the "Reset" button on the upper right next to the "Search" button. ## Public views -The exact appearance of the search interface will vary based on the [theme](/sites/site_theme/) selected. However, the way search works should be consistent regardless of theme. All of the screenshots in this section are from a site using the the Default theme. +The exact appearance of the search interface will vary based on the [theme](sites/site_theme) selected. However, the way search works should be consistent regardless of theme. All of the screenshots in this section are from a site using the the Default theme. ### Basic search There is a search bar near the menu for each site. In the default theme, it is located just beneath the main menu, as shown in the image below. @@ -154,7 +154,7 @@ If the [ ### Advanced item search Site visitors can access an advanced item search from the Browse Items page, if you have that page accessible. There is a link for Advanced search between the pagination and the sort options at the top of the item browse table. -![The Items page of the Jane Austen site, with a blue arrow pointing to the link for Advanced search](files/search_publicitems1) +![The Items page of the Jane Austen site, with a blue arrow pointing to the link for Advanced search](files/search_publicitems1.png) Clicking this loads a new page with four options for search: @@ -163,7 +163,7 @@ Clicking this loads a new page with four options for search: *Search by value:* search for a term or phrase using multiple options. - The first selector allows you to specify a property to search. - - Note that if you have have the [site settings](sites/site_settings/#search) to restrict search to templates, this will only display the properties used by those templates. + - Note that if you have have the [site settings](sites/site_settings.md#search) to restrict search to templates, this will only display the properties used by those templates. - The second selector allows you to set the relationship the property has with the value. The options are: - is exactly, - is not exactly, @@ -181,7 +181,7 @@ To find a resource ID, go to the resource and look at the url in your browser's *Search by item set:* select from a dropdown of item sets. -![Advanced item search fields as described](files/search_publicitems2) +![Advanced item search fields as described](files/search_publicitems2.png) Searches by value, class, and item set allow a visitor to search by more than one input; they can use the *add new* buttons to search with more than one search term. These search terms build - searching for two item sets will return all items in either item set, rather than only those items which are in both. @@ -199,7 +199,7 @@ Clicking the advanced search link loads a new page with three options for search *Search by value:* search for a term or phrase using multiple options. - The first selector allows you to specify a property to search. - - Note that if you have have the [site settings](sites/site_settings/#search) to restrict search to templates, this will only display the properties used by those templates. + - Note that if you have have the [site settings](sites/site_settings.md#search) to restrict search to templates, this will only display the properties used by those templates. - The second selector allows you to set the relationship the property has with the value. The options are: - is exactly, - is not exactly, diff --git a/docs/sites/index.md b/docs/sites/index.md index f5b854aa..f1481744 100644 --- a/docs/sites/index.md +++ b/docs/sites/index.md @@ -28,7 +28,7 @@ The Add New Site page has three tabs: Admin, Theme, and Item Pool. ### The Admin tab * Give your site a *title* (required) * create a *slug* for the site’s url. The url will be *installurl/site/slug*. This is optional - if you leave this field blank, Omeka S will create a slug based on the site title. -* Create a *summary* for your site, a brief idea of what it is about which will appear on your installation's landing page and on [list of site blocks](../sites/site_pages/#page-blocks) +* Create a *summary* for your site, a brief idea of what it is about which will appear on your installation's landing page and on [list of site blocks](site_pages.md#page-blocks) ![Admin tab for a new site with nothing entered](../sites/sitesfiles/sitesadd_admin.png) diff --git a/docs/sites/site_navigation.md b/docs/sites/site_navigation.md index 8324ec78..f5204c07 100644 --- a/docs/sites/site_navigation.md +++ b/docs/sites/site_navigation.md @@ -22,7 +22,7 @@ To change which page is used as the homepage, select a different page from the d ## Adding Navigation -Add to the navigation of the site using the options on the right hand side of the page. There are two sections: [Add a custom link](../sites/site_navigation/#custom-link) and [Add a link to a site page](../sites/site_navigation/#site-page) +Add to the navigation of the site using the options on the right hand side of the page. There are two sections: [Add a custom link](#add-a-custom-link) and [Add a link to a site page](#site-page) ### Add a custom link To add a link you can use the *Add a custom link* options on the right hand drawer to add: diff --git a/docs/sites/site_pages.md b/docs/sites/site_pages.md index cc446022..5ab13274 100644 --- a/docs/sites/site_pages.md +++ b/docs/sites/site_pages.md @@ -87,7 +87,7 @@ Some modules may create additional blocks for your site pages. For information o ### From the Public Side If you are on the admin side and click "View" in the upper right-hand corner of a page, it will take you to the public view for that page. -As you are browsing the public side of your site, you can edit the page you are viewing if you are currently logged in and the [user bar option is turned on in Site Settings](../sites/site_settings/#general-settings). +As you are browsing the public side of your site, you can edit the page you are viewing if you are currently logged in and the [user bar option is turned on in Site Settings](site_settings.md#general-settings). The user bar, which appears across the top of the page, includes a link to edit the current page - circled in red in the below image. @@ -208,7 +208,7 @@ You can add multiple items to the list. ### Item with Metadata This block displays an item along with all associated metadata (entered when creating or editing the [item](../content/items.md)). -Add attachments in the same manner as the [media](../sites/site_pages/#media) page block. +Add attachments in the same manner as the [media](#media-embed) page block. ![Item with metadata block with nothing attached](../sites/sitesfiles/sitepg_iwm.png) diff --git a/docs/sites/site_settings.md b/docs/sites/site_settings.md index 60e3ff2e..f361fbff 100644 --- a/docs/sites/site_settings.md +++ b/docs/sites/site_settings.md @@ -11,7 +11,7 @@ The site info settings for an Omeka S site are where you can change the basic in * *title* - a text field. * *slug* - the url for your site. -* *summary* - the brief description of what it is about which will appear on your installation's landing page and on [List of Site](../sites/site_pages/#page-blocks) blocks. +* *summary* - the brief description of what it is about which will appear on your installation's landing page and on [List of Site](site_pages.md#page-blocks) blocks. ![Site info for the site “Jane Austen” with buttons across the top to View, Delete, and Save the site](../sites/sitesfiles/sites_siteinfo.png) @@ -38,7 +38,7 @@ To implement any changes you make, click Save at the top right of the browser wi **Auto-assign new items** A checkbox which sets whether new items are automatically added to the site. If checked, every new item will be added to the site, regardless of the item's owner. Note that item owners may unassign their items from the site at any time, in the item's edit pages. -**Attachment link type** Sets the target of links from attachments you add to [site page blocks](../sites/site_pages/#page-blocks) (for example, in an [item showcase](../sites/site_pages/#item-showcase). It offers a dropdown with the following options: +**Attachment link type** Sets the target of links from attachments you add to [site page blocks](site_pages.md#page-blocks) (for example, in an [item showcase](site_pages.md#item-showcase). It offers a dropdown with the following options: - *item page:* clicking on the attachment takes users to the item page associated with the attached media; - *media page:* clicking on the attachment takes users to the media page; @@ -54,7 +54,7 @@ When users are logged in, the user bar has the following options: - Installation Title: takes you back to the installation admin - Site Title: takes you back to the landing page for managing the site (site/show). -- Resource view: depending on what you are viewing, this is a link to the admin side management for [Pages](../site/site_pages), [Items](../content/items), or [Item Sets](../content/item-sets) +- Resource view: depending on what you are viewing, this is a link to the admin side management for [Pages](site_pages), [Items](../content/items), or [Item Sets](../content/item-sets) - Edit link for that page, item set, or item. - User's display name: takes you to your user page. - Logout: logs out current user. diff --git a/docs/sites/site_theme.md b/docs/sites/site_theme.md index c4d22c76..9142595e 100644 --- a/docs/sites/site_theme.md +++ b/docs/sites/site_theme.md @@ -102,7 +102,7 @@ Settings not described above: * **Navigation layouts:** Global navigation can display as a **horizontal top bar with optional dropdown menus** or a **left vertical column**. * **Show Top Navigation Child Pages:** Toggle display of child pages within the main navigation. If unchecked, only the top-level navigation will display. * **Layout for Show Pages:** Resource metadata can show display as **stacked** with properties as headings above their values, or **inline** with properties as headings inline with their values. -* **Truncate Body Property:** Set how much of the [browse body property]( ) displays on the browse page. You can: +* **Truncate Body Property:** Set how much of the browse body property displays on the browse page. You can: * **Show full value** which displays all of the property text. * **Show 4 lines and fade out** which displays 4 lines of text with a fade at the end of the text block. * **Show 4 lines and ellipses** which displays 4 lines of text concluding with an ellipses (...) diff --git a/index.rst b/index.rst new file mode 100644 index 00000000..1584db93 --- /dev/null +++ b/index.rst @@ -0,0 +1,97 @@ +===================== + Omeka S User Manual +===================== + +Omeka S is a web publication system for universities, galleries, libraries, +archives, and museums. It creates a local network of independently curated +exhibits sharing a collaboratively built pool of items and their metadata. + +The sections of this manual correspond to the navigation sections on the +left-hand side of the :doc:`administrative dashboard `. +of an Omeka S Installation: + +Sites + Creating, editing, and managing sites, the public-facing parts of an Omeka S + installation. + +Resources + Creating, editing, and managing the content of an installation: items, item + sets, media, vocabularies, and resource templates. + +Admin + Access to functionality in the admin section varies by user role, but can + include: users, jobs, and settings. + +Modules + This section opens with basic information on managing the modules which + extend the functionality of your Omeka S installation and sites. It then + offers specific documentaiton for Omeka S modules created by RRCHNM, listed + in alphabetial order. + +This manual also includes a :doc:`glossary `, instructions on +conducting :doc:`searches `, and how to turn on :doc:`error +logging `. + +Screencasts to supplement the documentation are linked from relevant pages, and +can be browsed in the `Omeka S collection on Vimeo +`_. + +This documentation is CC-BY-NC + +.. toctree:: + :hidden: + + docs/accessibility + docs/s-planning-tips + docs/install + docs/admin-dashboard + docs/glossary + docs/search + docs/frontpage + +.. toctree:: + :hidden: + :caption: Sites + + docs/sites/index + docs/sites/site_settings + docs/sites/site_pages + docs/sites/site_navigation + docs/sites/site_resources + docs/sites/site_users + docs/sites/site_theme + +.. toctree:: + :hidden: + :caption: Resources + + docs/content/items + docs/content/item-sets + docs/content/media + docs/content/vocabularies + docs/content/resource-template + +.. toctree:: + :hidden: + :caption: Admin + + docs/admin/users + docs/admin/jobs + docs/admin/settings + docs/admin/assets + +.. toctree:: + :hidden: + :glob: + :caption: Modules + + docs/modules/index + docs/modules/* + +.. toctree:: + :hidden: + :caption: Miscellaneous + + docs/errorLogging + docs/translateOmekaS + docs/configuration diff --git a/make.bat b/make.bat new file mode 100644 index 00000000..2119f510 --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index ea586b8e..00000000 --- a/mkdocs.yml +++ /dev/null @@ -1,68 +0,0 @@ -site_name: Omeka S User Manual -theme: - name: 'readthedocs' - custom_dir: 'omeka/' - include_homepage_in_sidebar: false -repo_url: 'http://github.com/omeka/omeka-s-enduser' -extra_css: - - css/extra.css -markdown_extensions: - - toc: - permalink:  -nav: - - index.md - - accessibility.md - - s-planning-tips.md - - install.md - - admin-dashboard.md - - glossary.md - - search.md - - frontpage.md - - Sites: - - sites/index.md - - sites/site_settings.md - - sites/site_pages.md - - sites/site_navigation.md - - sites/site_resources.md - - sites/site_users.md - - sites/site_theme.md - - Resources: - - content/items.md - - content/item-sets.md - - content/media.md - - content/vocabularies.md - - content/resource-template.md - - Admin: - - admin/users.md - - admin/jobs.md - - admin/settings.md - - admin/assets.md - - Modules: - - modules/index.md - - modules/collecting.md - - modules/csseditor.md - - modules/csvimport.md - - modules/customvocab.md - - modules/dspaceconnector.md - - modules/extracttext.md - - modules/facetedbrowse.md - - modules/fedoraconnector.md - - modules/filesideload.md - - modules/itemcarouselblock.md - - modules/mapping.md - - modules/metadatabrowse.md - - modules/numericdatatypes.md - - modules/omeka2importer.md - - Scripto: - - modules/scripto/index.md - - modules/scripto/scriptoproject.md - - modules/scripto/themeingScripto.md - - modules/scripto/scriptoPublicView.md - - modules/scripto/troubleshootingScripto.md - - modules/sharing.md - - modules/valuesuggest.md - - modules/zoteroimport.md - - Miscellaneous: - - errorLogging.md - - translateOmekaS.md - - configuration.md diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..8c10e435 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,5 @@ +sphinx==3.5.4 +sphinx-intl==2.0.1 +sphinx_rtd_theme==0.5.2 +myst-parser==0.15.1 +docutils<0.17 diff --git a/translation.md b/translation.md new file mode 100644 index 00000000..c9210d16 --- /dev/null +++ b/translation.md @@ -0,0 +1,13 @@ +# How to translate documentation + +Steps to follow to translate in french: + +1. make gettext +2. sphinx-intl update --language fr +3. Translate the PO with Poedit +4. sphinx-intl build +5. make -e SPHINXOPTS="-D language='fr'" clean html + +## Sphinx configuration for translation + +https://www.sphinx-doc.org/en/3.x/usage/configuration.html#options-for-internationalization