Merge branch 'develop' into 3611-custom-dv-names #3611

IQSS · Jun 6, 2017 · ce77fa2 · ce77fa2
2 parents 77214a5 + dd39e8a
commit ce77fa2
Show file tree

Hide file tree

Showing 83 changed files with 1,171 additions and 78 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,8 @@
 # Contributing to Dataverse
 
-Thank you for your interest in contributing to Dataverse! We welcome contributions of ideas, bug reports, usability testing, documentation, code, and more!
+Thank you for your interest in contributing to Dataverse!  We are open to contributions from everyone. You don't need permission to participate, just jump in using the resources below.  If you have questions, reach out to us on the [#dataverse IRC channel][], and hang around a while, as it may take time for community members to de-idle.
+
+We aren't just looking for developers, there are many ways to contribute to Dataverse.  We welcome contributions of ideas, bug reports, usability research/feedback, documentation, code, and more!
 
 ## Ideas/Feature Requests
 

diff --git a/doc/sphinx-guides/source/admin/geoconnect-worldmap.rst b/doc/sphinx-guides/source/admin/geoconnect-worldmap.rst
@@ -1,10 +1,11 @@
 Geoconnect and WorldMap
 =======================
 
-.. contents:: :local:
-
 One of the optional components listed under "Architecture and Components" in the :doc:`/installation/prep` section of the Installation Guide is `Geoconnect <https://github.com/IQSS/geoconnect>`_, a piece of middleware that allows Dataverse users to create maps in `WorldMap <http://worldmap.harvard.edu>`_ based on geospatial data stored in Dataverse. For more details on the feature from the user perspective, see the :doc:`/user/data-exploration/worldmap` section of the User Guide.
 
+.. contents:: |toctitle|
+	:local:
+
 Update "mapitlink"
 ------------------
 

diff --git a/doc/sphinx-guides/source/admin/harvestclients.rst b/doc/sphinx-guides/source/admin/harvestclients.rst
@@ -1,8 +1,9 @@
 Managing Harvesting Clients
 ===========================
 
-.. contents:: :local:
-
+.. contents:: |toctitle|
+	:local:
+
 Your Dataverse as a Metadata Harvester
 --------------------------------------
 

diff --git a/doc/sphinx-guides/source/admin/harvestserver.rst b/doc/sphinx-guides/source/admin/harvestserver.rst
@@ -1,7 +1,8 @@
 Managing Harvesting Server and Sets
 ===================================
 
-.. contents:: :local:
+.. contents:: |toctitle|
+  :local:
 
 Your Dataverse as an OAI server
 -------------------------------

diff --git a/doc/sphinx-guides/source/admin/index.rst b/doc/sphinx-guides/source/admin/index.rst
@@ -10,7 +10,7 @@ This guide documents the functionality only available to the Dataverse Admin ("N
 
 These "superuser" tasks are managed via the new page called the Dashboard. A user logged in as a Dataverse Admin will see the Dashboard link rendered in the upper right corner of every Dataverse page. 
 
-Contents:
+**Contents:**
 
 .. toctree::
 

diff --git a/doc/sphinx-guides/source/admin/metadataexport.rst b/doc/sphinx-guides/source/admin/metadataexport.rst
@@ -1,7 +1,8 @@
 Metadata Export
 ===============
 
-.. contents:: :local:
+.. contents:: |toctitle|
+	:local:
 
 Automatic Exports
 -----------------

diff --git a/doc/sphinx-guides/source/admin/timers.rst b/doc/sphinx-guides/source/admin/timers.rst
@@ -3,10 +3,10 @@
 Dataverse Application Timers
 ============================
 
-.. contents:: :local:
-
 Dataverse uses timers to automatically run scheduled Harvest and Metadata export jobs. 
 
+.. contents:: |toctitle|
+	:local:
 
 Dedicated timer server in a Dataverse server cluster
 ----------------------------------------------------

diff --git a/doc/sphinx-guides/source/admin/troubleshooting.rst b/doc/sphinx-guides/source/admin/troubleshooting.rst
@@ -3,10 +3,11 @@
 Troubleshooting
 ===============
 
-.. contents:: :local:
-
 This new (as of v.4.6) section of the Admin guide is for tips on how to diagnose and fix system problems. 
 
+.. contents:: |toctitle|
+	:local:
+
 Deployment fails, "EJB Timer Service not available"
 ---------------------------------------------------
 

diff --git a/doc/sphinx-guides/source/api/apps.rst b/doc/sphinx-guides/source/api/apps.rst
@@ -5,7 +5,8 @@ The introduction of Dataverse APIs has fostered the development of apps that are
 
 The apps below are open source, demonstrating how to use Dataverse APIs. Some of these apps (and others) are built on :doc:`/api/client-libraries` that are available for Dataverse APIs.
 
-.. contents:: :local:
+.. contents:: |toctitle|
+	:local:
 
 Javascript
 ----------

diff --git a/doc/sphinx-guides/source/api/client-libraries.rst b/doc/sphinx-guides/source/api/client-libraries.rst
@@ -5,6 +5,9 @@ Currently there are client libraries for Python, R, and Java that can be used to
 
 Because Dataverse is a SWORD server, additional client libraries exist for Java, Ruby, and PHP per the :doc:`/api/sword` page.
 
+.. contents:: |toctitle|
+	:local:
+
 Python
 ------
 

diff --git a/doc/sphinx-guides/source/api/dataaccess.rst b/doc/sphinx-guides/source/api/dataaccess.rst
@@ -1,12 +1,11 @@
 Data Access API
 ===============
 
-.. contents:: :local:
-
-
 The Data Access API provides programmatic download access to the files stored under Dataverse. 
 More advanced features of the Access API include format-specific transformations (thumbnail generation/resizing for images; converting tabular data into alternative file formats) and access to the data-level metadata that describes the contents of the tabular files. 
 
+.. contents:: |toctitle|
+   :local:
 
 Basic File Access
 -----------------

diff --git a/doc/sphinx-guides/source/api/index.rst b/doc/sphinx-guides/source/api/index.rst
@@ -15,7 +15,7 @@ Rather than using a production installation of Dataverse, API users are welcome
 
 Please note that the APIs in this guide are shipped with the Dataverse software itself but additional APIs are available if you install the "miniverse" application from https://github.com/IQSS/miniverse and give it read only access to your production Dataverse database. http://dataverse.org/metrics is powered by miniverse.
 
-Contents:
+**Contents:**
 
 .. toctree::
 

diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst
@@ -9,7 +9,8 @@ Dataverse 4.0 exposes most of its GUI functionality via a REST-based API. Some A
 
 .. warning:: Dataverse 4.0's API is versioned at the URI - all API calls may include the version number like so: ``http://server-address//api/v1/...``. Omitting the ``v1`` part would default to the latest API version (currently 1). When writing scripts/applications that will be used for a long time, make sure to specify the API version, so they don't break when the API is upgraded.
 
-.. contents::
+.. contents:: |toctitle|
+    :local:
 
 Endpoints
 ---------

diff --git a/doc/sphinx-guides/source/api/search.rst b/doc/sphinx-guides/source/api/search.rst
@@ -1,7 +1,8 @@
 Search API
 ==========
 
-.. contents:: :local:
+.. contents:: |toctitle|
+    :local:
 
 About
 -----

diff --git a/doc/sphinx-guides/source/api/sword.rst b/doc/sphinx-guides/source/api/sword.rst
@@ -1,6 +1,12 @@
 SWORD API
 =========
 
+.. contents:: |toctitle|
+	:local:
+
+About
+-----
+
 SWORD_ stands for "Simple Web-service Offering Repository Deposit" and is a "profile" of AtomPub (`RFC 5023`_) which is a RESTful API that allows non-Dataverse software to deposit files and metadata into a Dataverse installation. :ref:`client-libraries` are available in Python, Java, R, Ruby, and PHP.
 
 Introduced in Dataverse Network (DVN) `3.6 <http://guides.dataverse.org/en/3.6.2/dataverse-api-main.html#data-deposit-api>`_, the SWORD API was formerly known as the "Data Deposit API" and ``data-deposit/v1`` appeared in the URLs. For backwards compatibility these URLs continue to work (with deprecation warnings). Due to architectural changes and security improvements (especially the introduction of API tokens) in Dataverse 4.0, a few backward incompatible changes were necessarily introduced and for this reason the version has been increased to ``v1.1``. For details, see :ref:`incompatible`.
@@ -17,8 +23,6 @@ As a profile of AtomPub, XML is used throughout SWORD. As of Dataverse 4.0 datas
 
 .. _SWORDv2 specification: http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html
 
-.. contents::
-
 .. _incompatible:
 
 Backward incompatible changes

diff --git a/doc/sphinx-guides/source/conf.py b/doc/sphinx-guides/source/conf.py
@@ -427,3 +427,7 @@
 intersphinx_mapping = {'http://docs.python.org/': None}
 # Suppress "WARNING: unknown mimetype for ..." https://github.com/IQSS/dataverse/issues/3391
 suppress_warnings = ['epub.unknown_project_files']
+rst_prolog = """
+.. |toctitle| replace:: Contents:
+.. |anotherSub| replace:: Yes, there can be multiple.
+"""
diff --git a/doc/sphinx-guides/source/developers/branching-strategy.rst b/doc/sphinx-guides/source/developers/branching-strategy.rst
@@ -2,7 +2,8 @@
 Branching Strategy
 ==================
 
-.. contents:: :local:
+.. contents:: |toctitle|
+	:local:
 
 Goals
 -----

diff --git a/doc/sphinx-guides/source/developers/coding-style.rst b/doc/sphinx-guides/source/developers/coding-style.rst
@@ -2,6 +2,9 @@
 Coding Style
 ============
 
+.. contents:: |toctitle|
+	:local:
+
 Like all development teams, the `Dataverse developers at IQSS <http://datascience.iq.harvard.edu/team>`_ have their habits and styles when it comes to writing code.
 
 A lot of it isn't written down, but a draft has been started at https://docs.google.com/document/d/1KTd3FpM1BI3HlBofaZjMmBiQEJtFf11jiiGpQeJzy7A/edit?usp=sharing

diff --git a/doc/sphinx-guides/source/developers/debugging.rst b/doc/sphinx-guides/source/developers/debugging.rst
@@ -2,6 +2,9 @@
 Debugging
 =========
 
+.. contents:: |toctitle|
+	:local:
+
 Logging
 -------
 

diff --git a/doc/sphinx-guides/source/developers/dev-environment.rst b/doc/sphinx-guides/source/developers/dev-environment.rst
@@ -2,7 +2,8 @@
 Development Environment
 =======================
 
-.. contents:: :local:
+.. contents:: |toctitle|
+	:local:
 
 Assumptions
 -----------

diff --git a/doc/sphinx-guides/source/developers/documentation.rst b/doc/sphinx-guides/source/developers/documentation.rst
@@ -2,6 +2,9 @@
 Documentation
 =============
 
+.. contents:: |toctitle|
+	:local:
+
 Quick Fix
 -----------
 
@@ -61,3 +64,13 @@ After sphinx is done processing the files you should notice that the html folder
 You can click on the files in the html folder to preview the changes.
 
 Now you can make a commit with the changes to your own fork in GitHub and submit a pull request to the dataverse repository.
+
+Table of Contents
+-----------------
+
+Every non-index page should use the following code to display a table of contents of internal sub-headings: ::
+
+	.. contents:: |toctitle|
+		:local:
+
+This code should be placed below any introductory text/images and directly above the first subheading, much like a Wikipedia page.
diff --git a/doc/sphinx-guides/source/developers/geospatial.rst b/doc/sphinx-guides/source/developers/geospatial.rst
@@ -2,6 +2,9 @@
 Geospatial Data
 ===============
 
+.. contents:: |toctitle|
+	:local:
+
 How Dataverse Ingests Shapefiles
 --------------------------------
 
@@ -171,4 +174,4 @@ The ``get_join_targets()`` function in ``dataverse_layer_services.py`` uses the
 Saving Join Target Information to Geoconnect Database
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``get_latest_jointarget_information()`` in ``utils.py`` retrieves recent JoinTarget Information from the database. (See the `utils code in GitHub <https://github.com/IQSS/geoconnect/blob/master/gc_apps/worldmap_connect/utils.py#L16>`_.)
+The ``get_latest_jointarget_information()`` in ``utils.py`` retrieves recent JoinTarget Information from the database. (See the `utils code in GitHub <https://github.com/IQSS/geoconnect/blob/master/gc_apps/worldmap_connect/utils.py#L16>`_.)
diff --git a/doc/sphinx-guides/source/developers/index.rst b/doc/sphinx-guides/source/developers/index.rst
@@ -6,7 +6,7 @@
 Developer Guide
 =======================================================
 
-Contents:
+**Contents:**
 
 .. toctree::
 

diff --git a/doc/sphinx-guides/source/developers/intro.rst b/doc/sphinx-guides/source/developers/intro.rst
@@ -4,6 +4,9 @@ Introduction
 
 Welcome! `Dataverse <http://dataverse.org>`_ is an `open source <https://github.com/IQSS/dataverse/blob/master/LICENSE.md>`_ project that loves `contributors <https://github.com/IQSS/dataverse/blob/master/CONTRIBUTING.md>`_!
 
+.. contents:: |toctitle|
+	:local:
+
 Intended Audience
 -----------------
 

diff --git a/doc/sphinx-guides/source/developers/making-releases.rst b/doc/sphinx-guides/source/developers/making-releases.rst
@@ -2,7 +2,8 @@
 Making Releases
 ===============
 
-.. contents:: :local:
+.. contents:: |toctitle|
+	:local:
 
 Bump Version Numbers
 --------------------

diff --git a/doc/sphinx-guides/source/developers/selinux.rst b/doc/sphinx-guides/source/developers/selinux.rst
@@ -2,7 +2,8 @@
 SELinux
 =======
 
-.. contents:: :local:
+.. contents:: |toctitle|
+    :local:
 
 Introduction
 ------------

diff --git a/doc/sphinx-guides/source/developers/testing.rst b/doc/sphinx-guides/source/developers/testing.rst
@@ -2,6 +2,9 @@
 Testing
 =======
 
+.. contents:: |toctitle|
+	:local:
+
 Unit Tests
 ----------
 

diff --git a/doc/sphinx-guides/source/developers/tools.rst b/doc/sphinx-guides/source/developers/tools.rst
@@ -4,7 +4,8 @@ Tools
 
 These are handy tools for your :doc:`/developers/dev-environment/`.
 
-.. contents:: :local:
+.. contents:: |toctitle|
+	:local:
 
 Netbeans Connector Chrome Extension
 +++++++++++++++++++++++++++++++++++

diff --git a/doc/sphinx-guides/source/developers/unf/index.rst b/doc/sphinx-guides/source/developers/unf/index.rst
@@ -4,15 +4,6 @@
 Universal Numerical Fingerprint (UNF)
 =====================================
 
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-   unf-v3
-   unf-v5
-   unf-v6
-
 .. figure:: ./img/unf-diagram.png
     :align: center
     :alt: alternate text
@@ -40,3 +31,12 @@ Learn more: Micah Altman, Jeff Gill and Michael McDonald, 2003,
 `Numerical Issues in Statistical Computing for the Social Scientist
 <http://datascience.iq.harvard.edu/publications/numerical-issues-statistical-computing-social-scientist>`_,
 New York: John Wiley.
+
+**Contents:**
+
+.. toctree::
+   :maxdepth: 2
+
+   unf-v3
+   unf-v5
+   unf-v6
diff --git a/doc/sphinx-guides/source/developers/unf/unf-v3.rst b/doc/sphinx-guides/source/developers/unf/unf-v3.rst
@@ -3,6 +3,9 @@
 UNF Version 3
 ===========================
 
+.. contents:: |toctitle|
+	:local:
+
 Version 3 of the UNF algorithm was used by the Dataverse Network software prior to version 2.0, and was implemented in R code. This algorithm was used on digital objects containing vectors of numbers, vectors of character strings, data sets comprising such vectors, and studies comprising one or more such data sets.
 
 The UNF V3 algorithm applied to the content of a data set or study is as follows:

diff --git a/doc/sphinx-guides/source/developers/unf/unf-v5.rst b/doc/sphinx-guides/source/developers/unf/unf-v5.rst
@@ -3,10 +3,13 @@
 UNF Version 5
 ================================
 
+.. contents:: |toctitle|
+	:local:
+
 **Important Update:**
 
-**UNF Version 5 has been in use by the Dataverse project since 2009. It was built into every version of the DVN, starting with 2.0 and up to 3.6.2. However, some problems were recently found in that implementation. Namely, in certain cases data normalization is not implemented fully to the spec. UNF signatures it generates are still reasonably strong statistically; however, this means that at least some of our signatures are not independently verifiable. I.e., if somebody fully implements their own version of UNF calculator, for certain datasets it would calculate signatures different from those generated by the DVN. Unless of course they implement it with the exact same bugs as ours.**
+UNF Version 5 has been in use by the Dataverse project since 2009. It was built into every version of the DVN, starting with 2.0 and up to 3.6.2. However, some problems were recently found in that implementation. Namely, in certain cases data normalization is not implemented fully to the spec. UNF signatures it generates are still reasonably strong statistically; however, this means that at least some of our signatures are not independently verifiable. I.e., if somebody fully implements their own version of UNF calculator, for certain datasets it would calculate signatures different from those generated by the DVN. Unless of course they implement it with the exact same bugs as ours.
 
-**To address this, the Project is about to release UNF Version 6. The release date is still being discussed. It may coincide with the release of Dataverse 4.0. Alternatively, the production version of DVN 3.6.3 may get upgraded to use UNF v6 prior to that. This will be announced shortly. In the process, we are solving another problem with UNF v5 - this time we've made an effort to offer very implementer-friendly documentation that describes the algorithm fully and unambiguously. So if you are interested in implementing your own version of a UNF calculator, (something we would like to encourage!) please proceed directly to the Version 6 documentation.**
+To address this, the Project is about to release UNF Version 6. The release date is still being discussed. It may coincide with the release of Dataverse 4.0. Alternatively, the production version of DVN 3.6.3 may get upgraded to use UNF v6 prior to that. This will be announced shortly. In the process, we are solving another problem with UNF v5 - this time we've made an effort to offer very implementer-friendly documentation that describes the algorithm fully and unambiguously. So if you are interested in implementing your own version of a UNF calculator, (something we would like to encourage!) please proceed directly to the Version 6 documentation.
 
-**Going forward, we are going to offer a preserved version of the Version 5 library and, possibly, an online UNF v5 calculator, for the purposes of validating vectors and data sets for which published Version 5 UNFs exist.**
+Going forward, we are going to offer a preserved version of the Version 5 library and, possibly, an online UNF v5 calculator, for the purposes of validating vectors and data sets for which published Version 5 UNFs exist.