From 7f322923245641ca9b7e4754e9ffd8c32529dc6d 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 | 2 + Makefile | 20 +++++ _docmap.md | 18 ---- conf.py | 64 ++++++++++++++ deploy | 4 +- docs/accessibility.md | 27 ------ docs/accessibility.rst | 36 ++++++++ docs/admin/users.md | 2 +- docs/content/item-sets.md | 2 +- docs/content/items.md | 2 +- docs/content/media.md | 4 +- docs/frontpage.md | 2 +- docs/index.md | 24 ----- docs/modules/csvimport.md | 8 +- docs/modules/fedoraconnector.md | 2 +- 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/sites/index.md | 4 +- index.rst | 101 ++++++++++++++++++++++ make.bat | 35 ++++++++ mkdocs.yml | 78 ----------------- requirements.txt | 5 ++ translation.md | 13 +++ 27 files changed, 316 insertions(+), 178 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 8b03c06b..058d5560 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ +_build/ +locales/**/*.mo site/ .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 0c154bc5..00000000 --- a/docs/accessibility.md +++ /dev/null @@ -1,27 +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/){target=_blank} and to be compliant with [Section 508](http://www.section508.gov/){target=_blank} of the Americans with Disabilities Act. - -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){target=_blank} (pdf), October 2020. -- Omeka S version 2.x [Accessibility Conformance Report using VPAT version 2.0](files/VPAT_OmekaS2-0-1.pdf){target=_blank} (pdf), August 2019. -- Omeka S version 1.x [Accessibility Conformance Report using VPAT version 1.1](files/VPAT2.0-OmekaS1-1.pdf){target=_blank} (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){target=_blank} (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..4509b934 --- /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 Omeka S themes produced by the Omeka team have 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 b97c157b..4164d581 100644 --- a/docs/admin/users.md +++ b/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. diff --git a/docs/content/item-sets.md b/docs/content/item-sets.md index ffdda0e5..b94cb4e6 100644 --- a/docs/content/item-sets.md +++ b/docs/content/item-sets.md @@ -125,7 +125,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 3eb6ca99..6a254382 100644 --- a/docs/content/items.md +++ b/docs/content/items.md @@ -214,7 +214,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 video 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 68f39905..94474655 100644 --- a/docs/content/media.md +++ b/docs/content/media.md @@ -27,7 +27,7 @@ Media are displayed in a table. Each media is a row, with columns for: 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. Clicking on the title of any media will take you to its metadata page. This page displays any metadata in the main work area, with a sidebar on the right listing the visibility, associated item (an active link), date created, MIME type, Size, Ingester, Source, and links to the file derivatives. @@ -57,7 +57,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) diff --git a/docs/frontpage.md b/docs/frontpage.md index d89f437f..3a46c8b4 100644 --- a/docs/frontpage.md +++ b/docs/frontpage.md @@ -12,4 +12,4 @@ If you want this index page to be hidden from site visitors, a Global Administra - Under the "Default site" option, use the dropdown menu to select one of your current sites. - To remove a selected site and revert back to the index page, click the small "X" on the right side of the dropdown. -You can customize a branded site index for your installation by creating a site, creating a page, and then using the ["List of sites" page block](sites/site_pages.md#page-blocks) to generate a list of all the sites in the installation. Then, use the "Default site" option to point to that site. \ No newline at end of file +You can customize a branded site index for your installation by creating a site, creating a page, and then using the ["List of sites" page block](sites/site_pages.md#page-blocks) to generate a list of all the sites in the installation. Then, use the "Default site" option to point to that site. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index e8f1a44f..00000000 --- a/docs/index.md +++ /dev/null @@ -1,24 +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 administrative interface varies by user role, but can include: users, jobs, assets, and settings. - -**Modules** -This section opens with basic information on managing the modules that extend the functionality of your Omeka S installation and sites. It then offers specific documentaiton for Omeka S modules created by the Omeka Team, 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){target=_blank}. - -
-

Omeka S Tour from Omeka on Vimeo.

diff --git a/docs/modules/csvimport.md b/docs/modules/csvimport.md index 4ddd0066..55e96616 100644 --- a/docs/modules/csvimport.md +++ b/docs/modules/csvimport.md @@ -689,7 +689,7 @@ The following are known errors that can occur during an import: Some other modules add functionality to the CSV import process. 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 type, 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 type, including Mixed Resources. ![Add mapping drawer with additional options for "Resource location" and "default map view"](../modules/modulesfiles/csvimport_mapping1.png) @@ -708,7 +708,7 @@ If you have [Mapping](../mapping/) (minimum version 1.1.0) installed and active, - **Default zoom** must 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". @@ -717,7 +717,7 @@ Everything on the **Map to Omeka S data** tab will be the same. When you add a m 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 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. Options are: @@ -756,4 +756,4 @@ Use the following formats for importing [durations](https://en.wikipedia.org/wik ### Custom Vocab -If you have [Custom Vocab](../customvocab) installed and active, it will add your custom vocabularies as data types in Omeka. You can select these data types during your CSV Import. +If you have [Custom Vocab](customvocab) installed and active, it will add your custom vocabularies as data types in Omeka. You can select these data types during your CSV Import. diff --git a/docs/modules/fedoraconnector.md b/docs/modules/fedoraconnector.md index 8762eb28..22026af3 100644 --- a/docs/modules/fedoraconnector.md +++ b/docs/modules/fedoraconnector.md @@ -11,7 +11,7 @@ There are two options for configuring Fedora Connector, both of which enable the The first checkbox offers the option to import the Fedora Vocabulary into your Omeka S install’s Vocabularies. The second checkbox offers the option to import the Linked Data Platform Vocabulary into your Omeka S install’s Vocabularies. If you do so, data in these vocabularies will also be imported into Omeka S. -You can check these boxes when you first install Fedora Connector, or at a later point via the "Configure" button in the [Modules](../modules/index.md#managing-modules) list. +You can check these boxes when you first install Fedora Connector, or at a later point via the "Configure" button in the [Modules](index) list. ## Import data To use Fedora Connector, navigate to the section labelled "Fedora Connector" under Modules in the left-hand navigation of the admin dashboard. This will automatically take you to the Import page. diff --git a/docs/modules/numericdatatypes.md b/docs/modules/numericdatatypes.md index 9a065b16..a1547cff 100644 --- a/docs/modules/numericdatatypes.md +++ b/docs/modules/numericdatatypes.md @@ -73,7 +73,7 @@ Clicking on this dropdown will reveal multiple options, including all of the pro ![The contents of the dropdown, with the normal options in addition to eight properties using numeric data types.](../modules/modulesfiles/ndt-browsesort2.png) ## 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-editing): Convert to Numeric. The Convert to Numeric option lets you convert an existing text input property to a numeric data type. It will not work on properties where the data is currently an Omeka resource or a URI. diff --git a/docs/modules/scripto.rst b/docs/modules/scripto.rst new file mode 100644 index 00000000..c53b25a1 --- /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 c77c2ae7..8757dcb4 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 7a9ee78c..25c22bea 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 dee58e40..a02b1502 100644 --- a/docs/modules/scripto/scriptoproject.md +++ b/docs/modules/scripto/scriptoproject.md @@ -81,7 +81,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. @@ -258,7 +258,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 03b0b64b..5814623b 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,27 +13,27 @@ 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? Will you require users to create accounts on your site? Familiarize yourself with [user roles and permissions](admin/users.md). diff --git a/docs/sites/index.md b/docs/sites/index.md index 607634b0..4493ba21 100644 --- a/docs/sites/index.md +++ b/docs/sites/index.md @@ -29,7 +29,7 @@ The "New site" page has two tabs: **Info** and **Theme**. * Give your site a **title** (required). * Create a **slug** for the site’s url. The url will be `youromekainstall.org/s/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 description of what it is about. The summary text will appear on your installation's landing page and on the [list of sites](../sites/site_pages#list-of-sites) page block. +* Create a **summary** for your site: a brief description of what it is about. The summary text will appear on your installation's landing page and on the [list of sites](site_pages.md#list-of-sites) page block. * Upload a **thumbnail** for your site, which will replace the summary text on the landing page or in the list of sites block. ![Admin tab for a new site with nothing entered](../sites/sitesfiles/sitesadd_admin.png) @@ -70,4 +70,4 @@ Site admin left hand navigation options are: - [Resources](../sites/site_resources.md), - [User permissions](../sites/site_users.md), - [Theme](../sites/site_theme.md), and -- Settings added by modules, if installed. \ No newline at end of file +- Settings added by modules, if installed. diff --git a/index.rst b/index.rst new file mode 100644 index 00000000..6dd5c218 --- /dev/null +++ b/index.rst @@ -0,0 +1,101 @@ +===================== + 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 administrative interface varies by user role, but can + include: users, jobs, assets, and settings. + +Modules + This section opens with basic information on managing the modules that + extend the functionality of your Omeka S installation and sites. It then + offers specific documentaiton for Omeka S modules created by the Omeka Team, + 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 +`_. + +.. raw:: html + +
+ +`Omeka S Tour `_ from `Omeka `_ on `Vimeo `_. + +.. 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 089b4898..00000000 --- a/mkdocs.yml +++ /dev/null @@ -1,78 +0,0 @@ -site_name: Omeka S User Manual -theme: - name: 'readthedocs' - custom_dir: 'omeka/' - include_homepage_in_sidebar: false -site_url: 'https://omeka.org/s/' -repo_url: 'http://github.com/omeka/omeka-s-enduser' -extra_css: - - css/extra.css -markdown_extensions: - - admonition - - attr_list - - 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/datacleaning.md - - modules/datavisualization.md - - modules/datarepositoryconnector.md - - modules/dspaceconnector.md - - modules/extractmetadata.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/omekaCimporter.md - - modules/ositemimporter.md - - modules/persistentidentifiers.md - - modules/redactvalues.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..4a87c1d3 --- /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/master/usage/configuration.html#options-for-internationalization