Updated documentation to include additional details on upgrading the …

…service and usage string information for pds-doi-init

README.md

@@ -60,17 +60,10 @@ Create a file in the base directory of the project named `pds_doi_service.ini`;
     url = https://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_JSON_1D00.JSON
     pds_node_identifier = 0001_NASA_PDS_1.pds.Node.pds.name
 
-    [LANDING_PAGES]
-    # template url, arguments are
-    # 1) product_class suffix, after _
-    # 2) lid
-    # 3) vid
-    url = https://pds.nasa.gov/ds-view/pds/view{}.jsp?identifier={}&version={}
-
     [OTHER]
     logging_level = INFO
     doi_publisher = NASA Planetary Data System
-    global_keyword_values = PDS; PDS4;
+    global_keyword_values = PDS,PDS4
     pds_uri = http://pds.nasa.gov/pds4/pds/v1
     transaction_dir = ./transaction_history
     db_file = doi.db

docs/source/installation/index.rst

@@ -154,6 +154,31 @@ your virtual environment::
 
   pip install --upgrade pds-doi-service
 
+Upgrades to the PDS DOI Service should typically not affect any existing transaction
+database, transaction history, or INI configuration settings. If an instance of
+the PDS DOI API is running, for example in a ``screen`` session, it is recommended that
+it be terminated before performing an upgrade.
+
+.. note::
+
+    An update to an existing virtualenv installation of the PDS DOI Service may fail
+    if the underlying minimum required Python version has changed. If so, a new
+    virtual environment should be created using the required version of Python, after
+    which the latest version of the Service may be installed into it. Consult the
+    installation instructions above on how to create a new virtual environment.
+
+..  note::
+
+    In rare circumstances, an upgrade may invalidate an existing transaction
+    database if the update includes a change to the underlying schema. Any such changes
+    will be clearly identified in the release notes for the version of the service.
+    The ``pds-doi-init`` script may be used in these circumstances to rebuild a fresh
+    transaction database and transaction history based on what is available on DataCite.
+    For this reason, it is recommended that any outstanding draft or review DOI
+    requests are finalized and released before performing an upgrade which invalidates
+    the transaction database. Consult the `usage`_ documentation for more details
+    on running ``pds-doi-init``.
+
 
 .. References:
 .. _usage: ../usage/index.html

docs/source/usage/index.rst

@@ -13,15 +13,15 @@ The DOI is then used to cite the digital object, especially in scientific papers
 
 In the context of PDS, publishing a new DOI follows this workflow:
 
-    - `Reserve`: Before a dataset is published in PDS, a DOI is reserved so the
+    - ``Reserve``: Before a dataset is published in PDS, a DOI is reserved so the
       researchers working with the digital resource can cite it at early stage.
-    - `Draft`: The metadata associated to an existing DOI is elaborated and validated.
-    - `Review`: Once all metadata has been properly associated to the DOI, the
+    - ``Draft``: The metadata associated to an existing DOI is elaborated and validated.
+    - ``Review``: Once all metadata has been properly associated to the DOI, the
       requester submits the DOI record for review to the PDS Engineering node.
-    - `Release`: After the PDS Engineering node determines that the DOI record is
+    - ``Release``: After the PDS Engineering node determines that the DOI record is
       filled out properly, the DOI and its metadata is officially registered at
       `DataCite`_ and made available for public discovery. If there any issues with
-      the reviewed record, PDS Engineering node may move the record back to `Draft`
+      the reviewed record, PDS Engineering node may move the record back to ``Draft``
       status for correction by the original submitter.
 
 The Draft and Release steps may be repeated multiple times to update the metadata
@@ -34,7 +34,7 @@ The metadata managed with DOIs is meant to be preserved and traceable, as it is
 used to permanently cite a digital resource. For this reason, all transactions,
 creations, and updates with the PDS DOI Service are registered in a local database.
 This database is used to track submissions-in-progress and help ensure the proper
-workflow (`Reserve` -> `Draft` -> `Review` -> `Release`) is enforced.
+workflow (``Reserve`` → ``Draft`` → ``Review`` → ``Release``) is enforced.
 
 Currently, the service provides a command line tool for use by a PDS Engineering
 Node operator interacting with the Discipline Nodes, as well as a web API and UI
@@ -43,11 +43,21 @@ to enable Discipline Nodes to directly manage their DOIs.
 Command Line Usage Information
 ------------------------------
 
+pds-doi-cmd
+^^^^^^^^^^^
+
 .. argparse::
    :module: pds_doi_service.core.actions.action
    :func: create_parser
    :prog: pds-doi-cmd
 
+pds-doi-init
+^^^^^^^^^^^^
+
+.. argparse::
+    :module: pds_doi_service.core.util.initialize_production_deployment
+    :func: create_cmd_parser
+    :prog: pds-doi-init
 
 .. _OSTI: https://www.osti.gov/data-services
 .. _DataCite: https://datacite.org

src/pds_doi_service/core/actions/draft.py

@@ -41,7 +41,7 @@ class DOICoreActionDraft(DOICoreAction):
     _name = "draft"
     _description = (
         "Update a record without submission to the service provider. Metadata "
-        "updates are pulled from the provided PDS4/DOI label."
+        "updates are pulled from the provided PDS4/DOI label"
     )
     _order = 10
     _run_arguments = ("input", "node", "submitter", "lidvid", "force", "keywords")