[SHARE-698][Task] Replace outdated model diagram with a link to the schema endpoint

Author: chrisseto

docs/harvesters_and_transformers.rst

@@ -1,7 +1,7 @@
 .. _harvesters-and-transformers:
 
 Harvesters and Transformers
-==========================
+===========================
 
 A `harvester` gathers raw data from a source using their API.
 
@@ -11,49 +11,31 @@ Start Up
 --------
 
     1. Install `Docker <https://docs.docker.com/engine/installation/>`_.
-    2. Make sure you're using Python3 - install with `conda <http://conda.pydata.org/miniconda.html>`_ , or `homebrew <http://blog.manbolo.com/2013/02/04/how-to-install-python-3-and-pydev-on-osx#2>`_
+    2. Make sure you're using Python3 - install with `miniconda <http://conda.pydata.org/miniconda.html>`_ , or `homebrew <http://blog.manbolo.com/2013/02/04/how-to-install-python-3-and-pydev-on-osx#2>`_
     3. Install everything inside a Virtual Enviornment - created with `Conda <http://conda.pydata.org/docs/using/envs.html>`_ or `Virtualenv <https://virtualenv.pypa.io/en/stable/>`_ or your python enviornment of choice.
 
 Installation (inside a virtual environment)::
 
     pip install -r requirements.txt
 
-    // Creates and starts containers for elasticsearch, rabbitmq,
+    // Creates, starts, and sets up containers for elasticsearch,
     // postgres, and the server
-    docker-compose up -d web
-
-    ./up.sh
-    ---------------- or ----------------
-    pg
-    createuser share
-    psql
-        CREATE DATABASE share;
-    python manage.py makemigrations
-    python manage.py maketriggermigrations
-    python manage.py makeprovidermigrations
-    python manage.py migrate
-    python manage.py createsuperuser
-
+    docker-compose build web
+    docker-compose run --rm web ./bootstrap.sh
 
 To run the server in a virtual environment instead of Docker::
 
-    docker stop share_web_1
+    docker-compose stop web
     python manage.py runserver
 
 To run celery worker::
 
     python manage.py celery worker -l DEBUG
 
-To monitor your celery tasks::
-
-    python manage.py celery flower
-
-Visit http://localhost:5555/dashboard to keep an eye on your harvesting and transforming tasks
-
 .. _running-sources:
 
 Running Existing Harvesters and Transformers
--------------------------------------------
+--------------------------------------------
 
 To see a list of all sources and their names for harvesting, visit https://share.osf.io/api/sources/
 
@@ -126,7 +108,7 @@ To automatically add all harvested and accepted documents to Elasticsearch::
 
 
 Writing a Harvester and Transformer
-----------------------------------
+-----------------------------------
 
 See the transformers and harvesters located in the ``share/transformers/`` and ``share/harvesters/`` directories for more examples of syntax and best practices.
 
@@ -162,10 +144,11 @@ Writing a source.yaml file
 The ``source.yaml`` file contains information about the source itself, and one or more configs that describe how to harvest and transform data from that source.
 
 .. code-block:: yaml
+
     name: com.example
     long_title: Example SHARE Source for Examples
     home_page: http://example.com/
-    user: providers.com.example
+    user: sources.com.example
     configs:
     - label: com.example.oai
       base_url: http://example.com/oai/
@@ -224,11 +207,11 @@ Best practices for writing a non-OAI Harvester
 .. _writing-transformers:
 
 Best practices for writing a non-OAI Transformer
-"""""""""""""""""""""""""""""""""""""""""""""""
+""""""""""""""""""""""""""""""""""""""""""""""""
 
 - The transformer should be defined in ``share/transformers/{transformer name}.py``.
 - When writing the transformer:
-    - Determine what information from the source record should be stored as part of the ``CreativeWork`` :ref:`model <creative-work>` (i.e. if the record clearly defines a title, description, contributors, etc.).
+    - Determine what information from the source record should be stored as part of the ``CreativeWork`` :ref:`model <share-models>` (i.e. if the record clearly defines a title, description, contributors, etc.).
     - Use the :ref:`chain transformer tools <chain-transformer>` as necessary to correctly parse the raw data.
         - Alternatively, implement ``share.transform.BaseTransformer`` to create a transformer from scratch.
     - Utilize the ``Extra`` class

docs/share_api.rst

@@ -487,7 +487,7 @@ Example Data
 
 
 Code Examples
-~~~~~~~~
+~~~~~~~~~~~~~
 
     Python
 

docs/share_models.rst

@@ -3,208 +3,8 @@
 SHARE Models
 ============
 
-Model Descriptions
-------------------
-
-SHARE model descriptions will be useful when writing normalizers for new providers.
-See existing provider normalizers for more detailed examples.
-
-.. _creative-work:
-
-Creative Work
-"""""""""""""
-
-**Metadata Fields:**
-
-- title
-- description
-- contributors
-- A list of contributors associated with the work, passed to the ``Person`` class via the ``Contributor`` class
-
-.. code-block:: python
-
-    class Person:
-        family_name = ctx.family_name
-        given_name = ctx.given_name
-
-    class Contributor:
-        cited_name = ctx.cited_name
-        person = Delegate(Person, ctx)
-
-    class CreativeWork:
-        contributors = Map(Delegate(Contributor), ctx.contributors)
-
-- awards
-    - A list of awards associated with the work, passed to the ``Award`` class via the ``ThroughAwards`` class
-
-.. code-block:: python
-
-    class Award:
-        description = ctx.award_description
-        url = ctx.<award_url>
-
-    class ThroughAwards:
-        award = Delegate(Award, ctx)
-
-    class CreativeWork:
-        awards = Map(Delegate(ThroughAwards), ctx.awards)
-
-- links
-   - A list of links associated with the work, passed to the ``Link`` class via the ``ThroughLinks`` class
-
-
-.. code-block:: python
-
-    class Link:
-        url = ctx.<url>
-        # The type field must be either 'doi', 'provider', or 'misc'.
-        # If the type field is always the same, it can be made Static,
-        # otherwise, a function should be written to determine the link type.
-        type = Static('provider')
-        # OR
-        type = RunPython('get_link_type', ctx.<url>):
-
-        def get_link_type(self, link):
-            if 'dx.doi.org' in link:
-                return 'doi'
-            return 'misc'
-
-    class ThroughLinks:
-        link = Delegate(Link, ctx)
-
-    class CreativeWork:
-        links = Map(Delegate(ThroughLinks), ctx.links)
-
-- publishers
-   - A list of publishers associated with the work, passed to the ``Publisher`` class via the ``Association`` class:
-
-.. code-block:: python
-
-    class Publisher:
-        name = ctx.publisher_name
-
-    class Association:
-        entity = Delegate(Publisher, ctx)
-
-    class CreativeWork:
-        publishers = Map(Delegate(Association), ctx.publishers)
-
-- funders
-  - A list of funders associated with the work, passed to a ``Funder`` class via the ``Association`` class (syntax follows the ``publishers`` example above).
-- institutions
-  - A list of institutions associated with the work, passed to an ``Institution`` class via the ``Association`` class (syntax follows the ``publishers`` example above).
-- organizations
-  - A list of organizations associated with the work, passed to an ``Organization`` class via the ``Association`` class (syntax follows the ``publishers`` example above).
-- subjects
-  - A list of subjects associated with the work, passed to the ``Subject`` class via the ``ThroughSubjects`` class:
-
-.. code-block:: python
-
-    class Subject:
-        name = ctx.subject_name
-
-    class ThroughSubjects:
-        link = Delegate(Subject, ctx)
-
-    class CreativeWork:
-        subjects = Map(Delegate(ThroughSubjects), ctx.subjects)
-
-- tags
-   - A list of tags associated with the work, passed to the ``Tag`` class via the ``ThroughTags`` class
-
-.. code-block:: python
-
-    class Tag:
-        name = ctx.<tag_name>
-
-    class ThroughTags:
-        tag = Delegate(Tag, ctx)
-
-    class CreativeWork:
-        tags = Map(Delegate(ThroughTags), ctx.tags)
-
-- date_created
-- date_published
-- date_updated
-- free_to_read_type
-- free_to_read_date
-- rights
-- language
-
- **Subclasses:**
-
-- ``Article``
-- ``Book``
-- ``ConferencePaper``
-- ``Dataset``
-- ``Dissertation``
-- ``Lesson``
-- ``Poster``
-- ``Preprint``
-- ``Presentation``
-- ``Project``
-- ``ProjectRegistration``
-- ``Report``
-- ``Section``
-- ``Software``
-- ``Thesis``
-- ``WorkingPaper``
-
-
-Person
-""""""
-
- **Metadata Fields:**
-
-- family_name
-- given_name
-- additional_name
-- suffix
-- identifiers
-  - A list of identifiers associated with a person (such as an ORCID), passed to the ``Identifier`` class via the ``ThroughIdentifiers`` class
-
-.. code-block:: python
-
-    class Identifier:
-        url = ctx.url
-
-    class ThroughIdentifiers:
-        identifier = Delegate(Identifier, ctx)
-
-    class Person:
-        identifiers = ctx.identifiers
-
-- emails
-    - A list of emails associated with a person, passed to the ``Email`` class via the ``PersonEmails`` class (syntax follows the ``identifiers`` example above).
-- affiliations
-    - A list of affiliations associated with a person, passed to an appropriate entity class via the ``Affiliation`` class
-
-.. code-block:: python
-
-    class Institution:
-        name = ctx.<institution_affiliation_name>
-
-    class Affiliation:
-        # The entity used here could be any of the entity subclasses (Institution, Publisher, Funder, Organization).
-        entity = Delegate(Institution, ctx)
-
-    class Person:
-        affiliations = Map(Delegate(Affiliation), ctx.<affiliations>)
-
-- location
-- url
-
-Entity
-""""""
-
- **Subclasses**
-  - ``Organization``
-  - ``Publisher``
-  - ``Funder``
-  - ``Institution``
-
-Model Diagram
--------------
-.. image:: _static/share_vertical_models.png
+Due to the nature of the data that are collected by SHARE, the schema model is subject to change.
 
+The current JSON Schema and field descriptions, when available, can be found in `our API`_.
 
+.. _our API: https://share.osf.io/api/v2/schema