.. jinja:: config

    {% set source_name = "source_titles" %}
    {% set source = config.sources[source_name] %}
    {% set source_name_nice = source_name|replace("_", " ")|title %}
    {% set has_descriptions = source.fields.values()|selectattr("is_documented")|rejectattr("description", "none")|list|length is greaterthan 0 %}


    .. _{{ source_name }}:

    {{ source_name_nice }}
    ++++++++++++++++++++++++++++++++

    The {{ source_name_nice }} :term:`source` is a curated database of publications 'containers', for example journals, preprint servers, book series and others. This is analogous to the 'source titles' facet available in the Dimensions web application. 

    This section provides information about the {{ source_name_nice }} :term:`source` ,
    listing each :term:`field` available for {{ source_name_nice }}, with details
    about the field value type, including whether it may be used as a :term:`facet`
    and whether it is a multi-value field. The table also contains information about whether
    the field may be used in the ``where`` section and whether the
    field the field may be used in the :ref:`entity fields <entity-filters>` filter.
    The page also lists the fields included in each :term:`fieldset` available
    for {{ source_name_nice }}, and each aggregation :term:`indicator` available.

    .. note::
       By default, {{ source_name_nice }} is sorted by the relevance, unless specified differently using :ref:`sort-phrase` option.

    {{ source_name_nice }} Fields
    -----------------------------

    Fields are used to perform :ref:`searches <field-searching>` on the source they belong to. Note: the :ref:`emptiness filters <emptiness-filters>` can be used on any field, irrespectively of whether filtering / faceting is enabled on them.

    .. list-table::
       :widths: auto
       :header-rows: 1

       * - Field
         - Type
         - Multi?
         - Filter?
         - Facet?
         {% if has_descriptions %}
         - Description
         {% endif %}
       {% for field in source.fields.values()|selectattr("is_documented")|rejectattr("deprecated")|sort %}
       * - ``{{ field.name }}``
         - {% if source.is_entity(field) %}Entity: :ref:`{{ field.documentation_type }} <{{ field.type }}>`{% else %}Literal: :ref:`{{ field.documentation_type }} <supported-types>`{% endif %}
         - {% if field.is_multi %}**✓**{% endif %}
         - {% if field.is_filter %}**✓**{% endif %}
         - {% if source.is_facet(field) %}**✓**{% endif %}
         {% if has_descriptions %}
         - {% if field.description is not none %}{{ field.description }}{% endif %} {% if field.long_description is not none %}[#{{source_name}}_{{field.name}}_long_desc]_{% endif %}   {% if field.valid_values %}Valid values: {% for val in field.valid_values|sort %} `{{ val }}`  {% endfor %} {% endif %}
         {% endif %}
       {% endfor %}


    {% for field in source.fields.values()|selectattr("is_documented")|selectattr("long_description")|sort %}
    .. [#{{source_name}}_{{field.name}}_long_desc] {{ field.long_description }}
    {% endfor %}


    .. _{{ source_name }}_model:

    {{ source_name_nice }} Links
    ------------------------------------------

    The diagram below provides an overview of the outgoing links from {{ source_name_nice }} to other sources.

    .. image:: _static/images/data-model-{{ source_name }}.png
      :width: 80%
      :align: center
      :alt: {{ source_name }} outgoing links



    {{ source_name_nice }} Fieldsets
    --------------------------------

    Fieldsets are used to specify :ref:`fields groups <fields-fieldset>` in the context of a return statement.

    .. list-table::
       :widths: auto
       :header-rows: 1

       * - Fieldset
         - Fields
       {% for fieldset in source.fieldset_names|sort|reverse %}
       {% if fieldset != "all" %}
       * - ``{{ fieldset }}``
         - {% for field in source.fieldset_fields(fieldset)|sort %}``{{ field }}``
           {% endfor %}
       {% endif %}
       {% endfor %}


    .. _{{ source_name }}_metrics:

    {{ source_name_nice }} Indicators
    ---------------------------------

    Indicators are used to :ref:`aggregate results <aggregations-phrase>` in the context of a :term:`facet` query.

    .. list-table::
       :widths: auto
       :header-rows: 1

       * - Indicator
         - Description
       {% if source.all_metrics %}
       {% for metric_name, metric in source.all_metrics|dictsort|reverse %}
       {% if metric.is_documented %}
       * - ``{{ metric_name }}``
       {% if metric.description %}
         - {{ metric.description }}
       {% else %}
         -
       {% endif %}
       {% endif %}
       {% endfor %}
       {% endif %}


    {% set has_descriptions = source.search_fields_raw.values()|rejectattr("description", "none")|list|length is greaterthan 0 %}

    {% if has_descriptions %}

    {{ source_name_nice }} Search Indexes
    ---------------------------------------

    Search indexes are used to perform :ref:`full-text searches <full-text-main>` on the source they belong to. The default search index, which is used if none other is specified, is ``{{ source.default_search_field_docs }}``.

    .. list-table::
      :widths: auto
      :header-rows: 1

      * - Search index
        - Supports :ref:`multi-index <multi-index-search>` search
        - Description
      {% if source.search_fields_raw %}
      {% for search_field_name, search_field in source.search_fields_raw|dictsort|reverse %}
      {% if not search_field.deprecated and search_field.description %}
      * - ``{{ search_field_name }}``
        - {% if search_field.multi_index_search %}**✓**{% endif %}
        - {% if search_field.description is not none %}{{ search_field.description }}{% endif %}
      {% endif %}
      {% endfor %}
      {% endif %}

    {% endif %}



    {{ source_name_nice }} Deprecations 
    ---------------------------------------

    This section lists fields and search fields that have been deprecated and should not be used. 
 

    Deprecated Fields
    =================

    {% if source.deprecated_fields %}
    .. list-table::
       :widths: auto
       :header-rows: 1

       * - Field
         - Deprecation Note
       {% for field in source.deprecated_fields|sort %}
       * - ``{{ field.name }}``
         {% if field.deprecated != True %}
         - Deprecated in favor of: ``{{ field.deprecated }}``
         {% else %}
         - {{ field.description }}
         {% endif %}
       {% endfor %}
    {% else %}
       {{ source_name_nice }} has no deprecated fields.
    {% endif %}


    Partially Deprecated Fields
    ===========================

    {% if source.partially_deprecated_fields %}
    On the following fields only certain features are deprecated (e.g. filtering or faceting).

    .. list-table::
       :widths: auto
       :header-rows: 1

       * - Field
         - Deprecated Features
       {% for field in source.partially_deprecated_fields|sort %}
       * - ``{{ field.name }}``
         {% if field.deprecated_features %}
         - {% for feature in field.deprecated_features %}**{{ feature }}** {% endfor %}
         {% endif %}
       {% endfor %}
    {% else %}
       {{ source_name_nice }} has no partially deprecated fields.
    {% endif %}


    Deprecated Search Indexes
    =========================

    {% if source.deprecated_search_fields %}
    .. list-table::
       :widths: auto
       :header-rows: 1

       * - Search Index
         - Deprecation Note
       {% for search_field_name, search_field in source.deprecated_search_fields|dictsort|reverse %}
       * - ``{{ search_field_name }}``
         {% if search_field.deprecated != True %}
         - Deprecated in favor of: ``{{ search_field.deprecated }}``
         {% else %}
         - {{ search_field.description }}
         {% endif %}
       {% endfor %}
    {% else %}
       {{ source_name_nice }} has no deprecated search indexes.
    {% endif %}