Added configuration docs

belbio_conf.yml.example

@@ -2,38 +2,37 @@
 
 # Location of this file can be found in one of the following locations
 #   first found is the one that is used
-#   - ./belbio_conf.yaml   (just a regular file in the local directory)
-#   - ./.belbio_conf       (a dotfile file, e.g. hidden, in local directory)
+#   - ./belbio_conf.yml    (just a regular file in the local directory or
+#                              any parent directory)
 #   - ~/.belbio_conf       (a dotfile in the home directory)
 
 
-# bel_lang package settings
-bel_lang:
-  default_bel_version: 2.0.0
+# bel package settings
+bel:
+  lang:
+    default_bel_version: 2.0.0
 
-  # Term Canonicalization and decanonicalization
-  # Note that we don't decanonicalize CHEBI (this is not necessarily a symmetric process)
-  canonical:
-    HGNC: ["EG", "SP"]
-    MGI: ["EG", "SP"]
-    RGD: ["EG", "SP"]
-    ZFIN: ["EG", "SP"]
-    SP: ["EG"]
-    CHEMBL: ["CHEBI"]
+    # Term Canonicalization and decanonicalization
+    # Note that we don't decanonicalize CHEBI (this is not necessarily a symmetric process)
+    canonical:
+      HGNC: ["EG", "SP"]
+      MGI: ["EG", "SP"]
+      RGD: ["EG", "SP"]
+      ZFIN: ["EG", "SP"]
+      SP: ["EG"]
+      CHEMBL: ["CHEBI"]
 
-  decanonical:
-    # EG will convert into the first valid namespace based on species
-    EG: ['HGNC', "MGI", 'RGD', "ZFIN", "SP"]
+    decanonical:
+      # EG will convert into the first valid namespace based on species
+      EG: ['HGNC', "MGI", 'RGD', "ZFIN", "SP"]
 
-# bel_nanopub package related settings
-bel_nanopub:
+  nanopub:
+    # JSON Schema for BEL Nanopubs (in YAML format :)
+    schema_uri: https://raw.githubusercontent.com/belbio/schemas/master/schemas/nanopub_bel-1.0.0.yaml
 
-  # JSON Schema for BEL Nanopubs (in YAML format :)
-  schema_uri: https://raw.githubusercontent.com/belbio/schemas/master/schemas/nanopub_bel-0.9.0.yaml
-
-  # Rules to apply for computing BEL Edges from BEL Nanopubs
-  # pipeline_edge_rules: ["component_of", "degradation"]
-  pipeline_edge_rules: []  # If empty, don't filter out any of the compute rules
+    # Rules to apply for computing BEL Edges from BEL Nanopubs
+    # pipeline_edge_rules: ["component_of", "degradation"]
+    pipeline_edge_rules: []  # If empty, don't filter out any of the compute rules
 
 # bel_api service settings
 bel_api:
@@ -47,7 +46,10 @@ bel_api:
   servers:
     server_type: DEV
 
-    # TODO - remove api_url in favor of top-level api value
+    # Require JWT token for authentication using shared_secret from belbio_secrets.conf?
+    # HTTP Header: Authorization: JWT xxxxxx.yyyyyyy.zzzzzz
+    authenticated: False
+
     # api_url: http://localhost:8181
     api_url: https://api.bel.bio/v1
 
@@ -64,19 +66,19 @@ bel_api:
 
 bel_resources:
 
-  # TODO - not currently implemented
   # restrict collecting to listed species, empty array means collect everything
   # species_list: ['TAX:9606', 'TAX:10090', 'TAX:10116']
   species_list: []
 
-  # Will download new source datafiles if older than 7 days if cannot determine
-  #    source file modification date (some FTP sites or Web files make it hard)
+  # Will download new source datafiles if older than 7 days if we cannot determine the
+  #    source file modification date (some FTP sites or Web files make it hard to figure
+  #    out when they were last modified).
   update_cycle_days: 7
 
   # Everything is relative to bel_resources root folder unless it starts with '/'
   file_locations:
 
-    # Root - root folder of bel_resources - added automatically - 2 levels above Config.py
+    # Root filepath defaults to the repository root with the tools and data sub-directories
     root: ''
 
     # Downloads - location for all source datafiles to be stored
@@ -94,19 +96,21 @@ bel_resources:
 
     # Namespaces metadata definition file
     namespaces_definition: resources/namespaces.yaml
-    # Logging configuration file
-    logging_conf_fn: logging-conf.yaml
 
-  # openbel related resource configuration
+  # OpenBel related resource configuration - these will eventually get converted
+  #   to native BELBio scripts as they don't provide for equivalents and other
+  #   enhancements to the namespaces available in BELBio
   openbel:
-    # Used to select what to convert using tools/terms/openbel_annotations.py
+    # Used to select what to convert using
+    #    github:belbio/bel_resources/tools/terms/openbel_annotations.py
     openbel_annotation_sources:
       Anatomy: http://resources.openbel.org/belframework/20150611/annotation/anatomy.belanno
       Cell: http://resources.openbel.org/belframework/20150611/annotation/cell.belanno
       CellLine: http://resources.openbel.org/belframework/20150611/annotation/cell-line.belanno
       Eco: http://belief-demo.scai.fraunhofer.de/openbel/repository/annotation/evidence.belanno
 
-    # Used to select what to convert using tools/terms/openbel_namespaces.py
+    # Used to select what to convert using
+    #   github:belbio/bel_resources/tools/terms/openbel_namespaces.py
     openbel_namespace_sources:
       AFFX: http://resources.openbel.org/belframework/20150611/namespace/affy-probeset-ids.belns
       # LMSD: http://belief-demo.scai.fraunhofer.de/openbel/repository/namespaces/LMSD.belns
@@ -121,3 +125,29 @@ bel_resources:
       SFAM: http://resources.openbel.org/belframework/20150611/namespace/selventa-protein-families.belns
       ZFIN: http://belief-demo.scai.fraunhofer.de/openbel/repository/namespaces/zfin-zebrafish-genes.belns
 
+# Controls logging for all tools
+logging:
+  version: 1
+  disable_existing_loggers: False
+  formatters:
+    simple:
+      format: '%(levelname)s::%(name)s::%(asctime)s   %(message)s'
+  handlers:
+    console:
+      class: logging.StreamHandler
+      level: INFO
+      formatter: simple
+      stream: ext://sys.stdout
+    # logfile:
+    #   class: logging.FileHandler
+    #   formatter: simple
+    #   filename: '../api.log'
+  loggers:
+    elasticsearch:
+      level: WARNING
+    urllib3:
+      level: CRITICAL
+  root:
+    level: INFO
+    handlers: [console]
+    # handlers: [console, logfile]

belbio_secrets.yml.example

@@ -1,5 +1,15 @@
-# belbio secrets
+# belbio secrets - added to config['secrets']
+
+# Location of this file can be found in one of the following locations
+#   first found is the one that is used
+#   - ./belbio_secrets.yml    (just a regular file in the local directory
+#                              or any parent directory)
+#   - ~/.belbio_secrets       (a dotfile in the home directory)
+
+
 bel_api:
-    arangodb_password: ''
     shared_secret: testme  # shared secret to validate JWT token
+    servers:
+        arangodb_password: ''
+
 

docs/source/configuration.rst

@@ -0,0 +1,29 @@
+Configuration
+===============
+
+All of the BELbio tools share the same configuration files. There are separate sections for configuration that is specific to a particular application or tool (e.g. bel_api, bel_resources or bel python package).
+
+Location
+------------
+
+Get first belbio_conf.{yml|yaml} and belbio_secrets.{yml|yaml} files in:
+    1. current dir or parent directories starting with immediate parent of current dir
+    2. OR
+    3. ~/.belbio_{conf|secrets}   (dotfiles in home directory)
+
+Download example files from:
+
+* `BELBio Conf <https://raw.githubusercontent.com/belbio/bel/master/belbio_conf.yml.example>`_
+* `BELBio Secrets <https://raw.githubusercontent.com/belbio/bel/master/belbio_secrets.yml.example>`_
+
+Main Configuration File
+--------------------------
+
+.. include:: ../../belbio_conf.yml.example
+    :code: yaml
+
+Secrets Configuration File
+-----------------------------
+
+.. include:: ../../belbio_secrets.yml.example
+    :code: yaml

docs/source/index.rst

@@ -50,12 +50,12 @@ Informational badges
    :alt: Maintainability
 
 
-
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    overview
+   configuration
    script
    modules
    lang