On this page:

• Glossary
• Installation
• Typical usage
• Notes for those of us who don't know Django

Glossary

Note: Over the course of the project, the terminology has changed, with the result that different areas of the codebase use different names for the same concepts.

While we aspire to eventually to update for consistency, in the meantime, these three terms listed below are used interchangeably in code. The first listed option (in bold) is the one currently used by the project, and the term used in the database is indicated by db:

• source / citation db
  The document that contains the Records. A Source includes bibliographic information (e.g. author, title, ...)
• record / item / reference db
  The bit of text within the Source that describes a group of Referents (references to people) as well as an event or situation with date, location, etc. Typical Record types include self-emancipation notices (aka "Escape Slave ads") or a single baptismal record
• referent db / person / entrant
  A reference to a person contained in a Record. Note that we reserve the term Person to indicate a particular individual. There may be multiple references to the same Person across different Records, and therefore there may be multiple Referents that in fact are the same Person

Installation

(Assumes Docker is installed and running.)

• Create a local "stuff" directory (name it anything) -- and from your terminal, cd into it (one-time step)

From the terminal, run:

• git clone git@github.com:Brown-University-Library/stolen_relations_start_data.git
  (a one-time step; downloading the SR data) Note that this is a private repo, for now; the data is not yet publicly available
• git clone git@github.com:Brown-University-Library/disa_dj_project.git
  (a one-time step, downloads the SR codebase)
• cd disa_dj_project
  Sets the current directory to disa_dj_project
• docker-compose up
  Creates the container (which starts the webapp)

The webapp should be running; from a browser, go to http://127.0.0.1:8000/version/ or http://127.0.0.1:8000/login/.

Typical usage

• cd <SOME_PATH>/disa_dj_project
  Sets the current directory to disa_dj_project
• docker-compose up
  Creates the container (which starts the webapp)

Note: if a code-update installs a new python-package, either:

• delete the disa_dj_project-web image which should force it to be rebuilt (best option), or...
• run docker-compose up --build to force the container to be rebuilt. (I don't think this actually creates a new image, so subsequent runs of docker-compose up will still use the old image.)

Notes for those of us who don't know Django

Some critical files:

disa_dj_project/config/settings.py

Django settings for disa_project. Mostly "where are things" and security keys, etc.

Generated by 'django-admin startproject' using Django 1.11.

More information on this file

Full list of settings and their values

disa_dj_project/config/urls.py

Maps URL patterns to views, e.g.:

url( r'^editor/documents/(?P<cite_id>.*)/$', views.edit_citation, name='edit_citation_url' )

which maps to the function definition in disa_dj_project/disa_app/views.py:

@shib_login
def edit_citation( request, cite_id=None ):

disa_dj_project/disa_app/admin.py

Seems to extend administrative functions, and handles the "marked for deletion" system. Contains 3 class definitions:

• MarkedForDeletionAdminForm
• UserProfileAdmin
• MarkedForDeletionAdmin

disa_dj_project/disa_app/disa_app_templates

The templates for the public pages. These files are referenced in disa_app/views.py.

disa_dj_project/disa_app/lib

A bunch of DISA-specific python code. This seems to be the main code area.

Includes:

• generate_browse_data.py
• a bunch of view_*_manager.py

disa_dj_project/disa_app/models_sqlalchemy.py

Model definition for SQL Alchemy

disa_dj_project/disa_app/models.py

Not sure (ask Birkin)

disa_dj_project/disa_app/settings_app.py

Some random settings—authentication, DB location, etc. Not sure how this relates to disa_dj_project/config/settings.py

disa_dj_project/disa_app/views.py

A bunch of routines that are called by disa_dj_project/config/urls.py and reference disa_dj_project/disa_app/disa_app_templates.