Skip to content

Commit

Permalink
fixes #21 - finishes the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@balmas
balmas committed May 26, 2017
1 parent ab6829c commit acdd463
Show file tree
Hide file tree
Showing 2 changed files with 130 additions and 84 deletions.
212 changes: 129 additions & 83 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,19 @@ Full Documentation at http://digital-milliet.readthedocs.io/en/latest/
Overview
========

The Digitat Milliet is a Python Flask Application backed by a Mongo DB database. It supports the creation and display
of an interactive collection of ancient Greek and Latin texts about painting. It is a digital interpretation of
"The Recueil des textes grecs et latins relatifs à la peinture ancienne" (“Collection of Greek and Latin Texts
Concerning Ancient Painting”), the initiative of a French academic painter, Paul Milliet, who had a passion for ancient
Greek culture.
The Digitat Milliet supports the creation and display of an interactive collection of ancient Greek and Latin texts about
painting. It is a digital interpretation of "The Recueil des textes grecs et latins relatifs à la peinture ancienne"
(“Collection of Greek and Latin Texts Concerning Ancient Painting”), the initiative of a French academic painter,
Paul Milliet, who had a passion for ancient Greek culture.

.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/dmhome.png?raw=true

.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/dmbrowse.png?raw=true

.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/dmread.png?raw=true

The Digital Milliet is implmented as a Flask Application, backed by a MongoDB database, supported by external
web services.

Installation Instructions
*************************
Expand Down Expand Up @@ -68,59 +76,57 @@ Or deploy in Docker container
For production deployment, see Puppet manifests in the puppet subdirectory of this repository.

Design: Motivation, Standards, Dependencies
**************************************************
The aim behind the design of the application was to support the representation of each entry in the original "Recueil"
as a graph of annotations.

The primary annotation of a Digital Milliet graph/record set is a Commentary targeting
a stable CTS URN identifier of the primary source Greek or Latin text which was the subject of the entry in the "Receuil".
This commentary annotation gets assigned an identifier which includes the original number of the entry in the "Receui".
Throughout the code and interface, this is referred to as the "Milliet Number".

Additional annotations in each graph include a Bibliography, French and English translations of the primary source text,
as well as images representing the described artwork or related material and semantic tag annotations on the images,
the primary source texts, the translations and the commentary.

Entries are indexed for browsing both by Milliet Number and Author/Work/Passage of the target primary source text passage.

The Digital Milliet application retrieves Author and Work metadata for each primary source text is from the
Perseus Catalog (http://catalog.perseus.org/).
Configuration
*************
All deployment specific variables and dependencies are specified in an external configuration file. By default the application looks for a configuration file named `config.cfg` in the digital_milliet base directory. An alternate
path can be supplied in an argument to the DigitalMilliet Flask Application:

We have used a non-standard form of a CITE URN to assign identifiers to each individual annotation in the graph. This may
eventually be replaced by UUIDs or other identifier system.
.. code-block:: python
In order to facilitate data reuse and interoperability we represent these annotations according to the Open Annotation
data model, a standard data model for serializing annotations on resources in the world wide web.
(This model has now evolved into the W3C Web Annotation Model).
DigitalMilliet(app, config_file="path/to/your/config.cfg")
The original design called for primary source texts and translations to be identified only by their CTS URN identifiers
and all textual passages retrieved at runtime from CTS Repositories.
However, as many of the texts and/or translations we need to refer to are not yet available online at a published CTS
API endpoint, and the stability and long term sustainability of such end points are not clear, the application design
was changed to enabled textual content to be included in addition to or instead of the CTS URN identifier of a text or
translation.
The default contents of this configuration file, with explanation of each setting, is provided below:

The Digital Milliet application depends upon components of the CapiTainS suite (https://github.com/capitains)
for its interaction with CTS endpoints and validation of CTS URN syntax.
.. code-block:: shell
The application uses the IIIF standard for image referencing and annotations and reuses the open source
Mirador Viewer (http://projectmirador.org/) to provide image display and annotation functionality.
# Name of the Mongo database
MONGO_DBNAME = 'app'
A design for semantic tagging of textual content has not yet been decided upon.
# Secret key for Flask session
SECRET_KEY = 'development is fun'
# Perseids OAUTH Setup
# OAUTH_CONSUMER_KEY and OAUTH_CONSUMER_SECRET must be supplied by Perseids Administrator for Production use
OAUTH_NAME = "digitalmilliet"
OAUTH_CONSUMER_KEY = 'dummy'
OAUTH_CONSUMER_SECRET = 'dummy'
OAUTH_REQUEST_TOKEN_PARAMS = {'scope': 'read'}
OAUTH_BASE_URL = 'https://sosol.perseids.org/sosol/api/v1/'
OAUTH_ACCESS_TOKEN_URL = 'https://sosol.perseids.org/sosol/oauth/token'
OAUTH_ACCESS_TOKEN_METHOD = "POST"
OAUTH_REQUEST_TOKEN_URL = None
OAUTH_AUTHORIZE_URL = 'https://sosol.perseids.org/sosol/oauth/authorize'
OAUTH_CALLBACK_URL = 'https://digmill.perseids.org/digmil/oauth/authorized'
Workflow
********
# Name of the collection for author records (future proofing to enable move to a separate collection)
AUTHORS_COLLECTION = "annotation"
The primary workflow for entering a new entry in the Digital Milliet is described in the diagram below.
# Set this to the ID for the Perseids community id in which membership enables Digital Milliet editorial permissions
ENFORCE_COMMUNITY_ID = None
.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/digitalmillietnewcommentaryworkflow.png?raw=true
# Not to be used in Production: eases development without OAuth Setup
OAUTH_USER_OVERRIDE = { 'oauth_user_uri' : 'http://sampleuseruri', 'oauth_user_name': 'Sample User' }
Individual components of an entry can also be edited or added separately after the initial data entry, via the Edit interface.
# Perseus Catalog API - Used for Lookup of Author and Work Metadata
CATALOG_API_URL = 'http://catalog.perseus.org/cite-collections/api'
CITE_URI_PREFIX = 'http://perseids.org/collections/'
CITE_COLLECTION = 'urn:cite:perseus:digmil'
Image annotations can be added, edited and deleted directly using the Mirador viewer.
# CTS API Endpoint for Retrieval of Primary Source Texts and Translations
CTS_BROWSE_URL = 'https://cts.perseids.org'
CTS_API_URL = 'https://cts.perseids.org/api/cts/'
CTS_API_VERSION = 5
Authentication and Authorization
********************************
Expand Down Expand Up @@ -166,54 +172,94 @@ must be a member of the Perseids Community with that id in order to be able to c
Digital Milliet. If the `ENFORCE_COMMUNITY_ID` setting is left empty, this functionality is disabled and all
authenticated users can create, edit or delete entries.
Configuration
*************
All deployment specific variables and dependencies are specified in an external configuration file. By default the application looks for a configuration file named `config.cfg` in the digital_milliet base directory. An alternate
path can be supplied in an argument to the DigitalMilliet Flask Application:
Design: Motivation, Standards, Dependencies
**************************************************
The aim behind the design of the application was to support the representation of each entry in the original "Recueil"
as a graph of annotations.
.. code-block:: python
The primary annotation of a Digital Milliet graph/record set is a Commentary targeting
a stable CTS URN identifier of the primary source Greek or Latin text which was the subject of the entry in the "Receuil".
This commentary annotation gets assigned an identifier which includes the original number of the entry in the "Receui".
Throughout the code and interface, this is referred to as the "Milliet Number".
DigitalMilliet(app, config_file="path/to/your/config.cfg")
Additional annotations in each graph include a Bibliography, French and English translations of the primary source text,
tags (freeform and semantic) as well as images representing the described artwork or related material. The images can
also be annotated.
Entries are indexed for browsing both by Milliet Number and Author/Work/Passage of the target primary source text passage.
The default contents of this configuration file, with explanation of each setting, is provided below:
The Digital Milliet application retrieves Author and Work metadata for each primary source text is from the
Perseus Catalog (http://catalog.perseus.org/).
.. code-block:: shell
We have used a non-standard form of a CITE URN to assign identifiers to each individual annotation in the graph. This may
eventually be replaced by UUIDs or other identifier system.
# Name of the Mongo database
MONGO_DBNAME = 'app'
In order to facilitate data reuse and interoperability we represent these annotations according to the Open Annotation
data model (http://www.openannotation.org/), a standard data model for serializing annotations on resources in the world wide web.
(This model has now evolved into the W3C Web Annotation Model). Image annotations adhere to the IIIF standard (http://iiif.io).
# Secret key for Flask session
SECRET_KEY = 'development is fun'
The original design called for primary source texts and translations to be identified only by their CTS URN identifiers
and all textual passages retrieved at runtime from CTS Repositories.
# Perseids OAUTH Setup
# OAUTH_CONSUMER_KEY and OAUTH_CONSUMER_SECRET must be supplied by Perseids Administrator for Production use
OAUTH_NAME = "digitalmilliet"
OAUTH_CONSUMER_KEY = 'dummy'
OAUTH_CONSUMER_SECRET = 'dummy'
OAUTH_REQUEST_TOKEN_PARAMS = {'scope': 'read'}
OAUTH_BASE_URL = 'https://sosol.perseids.org/sosol/api/v1/'
OAUTH_ACCESS_TOKEN_URL = 'https://sosol.perseids.org/sosol/oauth/token'
OAUTH_ACCESS_TOKEN_METHOD = "POST"
OAUTH_REQUEST_TOKEN_URL = None
OAUTH_AUTHORIZE_URL = 'https://sosol.perseids.org/sosol/oauth/authorize'
OAUTH_CALLBACK_URL = 'https://digmill.perseids.org/digmil/oauth/authorized'
However, as many of the texts and/or translations we need to refer to are not yet available online at a published CTS
API endpoint, and the stability and long term sustainability of such end points are not clear, the application design
was changed to enabled textual content to be included in addition to or instead of the CTS URN identifier of a text or
translation.
# Name of the collection for author records (future proofing to enable move to a separate collection)
AUTHORS_COLLECTION = "annotation"
The Digital Milliet application depends upon components of the CapiTainS suite (https://github.com/capitains)
for its interaction with CTS endpoints and validation of CTS URN syntax.
# Set this to the ID for the Perseids community id in which membership enables Digital Milliet editorial permissions
ENFORCE_COMMUNITY_ID = None
The application uses the IIIF standard for image referencing and annotations and reuses the open source
Mirador Viewer (http://projectmirador.org/) to provide image display and annotation functionality.
# Not to be used in Production: eases development without OAuth Setup
OAUTH_USER_OVERRIDE = { 'oauth_user_uri' : 'http://sampleuseruri', 'oauth_user_name': 'Sample User' }
Workflow
********
# Perseus Catalog API - Used for Lookup of Author and Work Metadata
CATALOG_API_URL = 'http://catalog.perseus.org/cite-collections/api'
CITE_URI_PREFIX = 'http://perseids.org/collections/'
CITE_COLLECTION = 'urn:cite:perseus:digmil'
The primary workflow for creating a new entry in the Digital Milliet is described in the diagram below.
.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/digitalmillietnewcommentaryworkflow.png?raw=true
Individual components of an entry can also be edited or added separately after the initial data entry, via the Edit interface.
To create a new entry, you click the Add Record button to bring up the Create form:
.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/dmnew.png?raw=true
Use the typeahead features in the 'Search for a Primary Source Passage' to search for an existing text in the CTS Repository
.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/dmnew2.png?raw=true
If found, you can enter the passage range you are interested in and then click 'Retrieve' to to retrieve the text.
If text you need is not found you can supply the text yourself in the input box.
Proceed to enter commentary text, tags and bibliography. Follow the same procedure for translations as you did for
the primary source text.
.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/dmnew3.png?raw=true
If an image you want to associate with the entry is available in from an IIIF-compliant image server you can enter
the publisher and URL of the IIIF manifest. This can be an image manifest, or a canvas manifest.
.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/dmnew4.png?raw=true
To edit an existing entry, you click the Edit button next to the Digital Milliet number on the Browse display. You
must be logged into see this option.
Editing proceeds similarly to the process for creating a new entry.
.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/dmedit.png?raw=true
Image annotations can be viewed, added, edited and deleted directly using the Mirador viewer.
.. image:: https://github.com/perseids-project/digital_milliet/blob/master/doc/dmimage.png?raw=true
Click on the bubble icon to view annotations on the image. Hover your mouse over the marked up areas on the image
to see the annotation text.
If you are logged in you can click Edit or Delete to edit or delete the image annotation.
You use the drawing tools in the Mirador viewer to create new annotations. Select a tool and drag the mouse to
highlight the region of interest on the image. When you release the mouse the annotation dialog will popup and you can
enter and save your annotation text.
# CTS API Endpoint for Retrieval of Primary Source Texts and Translations
CTS_BROWSE_URL = 'https://cts.perseids.org'
CTS_API_URL = 'https://cts.perseids.org/api/cts/'
CTS_API_VERSION = 5
2 changes: 1 addition & 1 deletion digital_milliet/lib/commentaries.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -614,7 +614,7 @@ def get_existing_tags(self):
""" List all existing tag body values
:return: tags and semantic tags
:rtype tuple
:rtype: tuple
"""
tag_list = self.mongo.db.annotation.find({"tags": {'$exists': 1}, '$where': "this.tags.length>0"})
tags = {}
Expand Down

0 comments on commit acdd463

Please sign in to comment.