<commit_before>Configuration
#############

There are a few different configuration files used by MapProxy.

``mappproxy.yaml``
    This is the main configuration of MapProxy. It configures all aspects of the server:
    Which servers should be started, where comes the data from, what should be cached,
    etc..
    
``seed.yaml``
    This file is the configuration for the ``mapproxy-seed`` tool. See :doc:`seeding documentation <seed>` for more information.

``develop.ini`` or ``config.ini``
    These are the paster configuration files that are used to start MapProxy in development or production mode. See :doc:`deployment documentation <deployment>` for more information.


.. note:: The configuration changed with the 0.9.0 release and you have to update any older configuration. This is a one-time change and further versions will offer backwards-compatibility. Read the :doc:`migration guide <migrate>` for some help.

.. index:: mapproxy.yaml

mapproxy.yaml
=============

The configuration uses the YAML format.

The MapProxy configuration is grouped into six sections, each configures a different aspect of MapProxy. These are the following sections:

- ``globals``:  Internals of MapProxy and default values that are used in the other configuration sections.
  
- ``services``:
  The services MapProxy offers, e.g. WMS or TMS.

- ``sources``: Define where MapProxy can retrieve new data.

- ``caches``: Configure the internal caches.

- ``layers``: Configure the layers that MapProxy offers. Each layer can consist of multiple sources and caches.
  
- ``grids``: Define the grids that MapProxy uses to aligns cached images.
  
The order of the sections is not important, so you can organize it your way.

.. note:: The indentation is significant and shall only contain space characters. Tabulators are **not** permitted for indentation.

.. #################################################################################

.. index:: services

services
--------

Here you can configure which services should be started. The configuration for all services is described in the :doc:`services` documentation.

Here is an example::

  services:
    tms:
    wms:
      md:
        title: MapProxy Example WMS
        contact:
        # [...]

.. #################################################################################
.. index:: layers

layers
------

Here you can define all layers MapProxy should offer. The layer definition is similar to WMS: each layer can have a name and title and you can nest layers to build a layer tree.

Layers should be configured as a list (``-`` in YAML), where each layer configuration is a dictionary (``key: value`` in YAML)

::

  layers:
    - name: layer1
      title: Title of Layer 1
      sources: [cache1, source2]
    - name: layer2
      title: Title of Layer 2
      sources: [cache3]

Each layer contains information about the layer and where the data comes from.

``name``
"""""""""

The name of the layer. You can omit the name for group layers (e.g. layers with ``layers``), in this case the layer is not addressable in WMS and used only for grouping.

.. versionchanged:: 0.9.2

The old syntax to configure each layer as a dictionary, with the key as the name, is deprecated since 0.9.2.

::

 - mylayer:
    title: My Layer
    source: [mysoruce]

should become

::

 - name: mylayer
   title: My Layer
   source: [mysoruce]


``title``
"""""""""
Readable name of the layer, e.g WMS layer title.


``layers``
""""""""""

.. versionadded:: 0.9.2

Each layer can contain another ``layers`` configuration. You can use this to build a nested layer tree.

For exmaple::

  layers:
    - name: layer1
      title: Title of Layer 1
      layers:
        - name: layer1a
          title: Title of Layer 1a
          sources: [source1a]
        - name: layer1b
          title: Title of Layer 1b
          sources: [source1b]
    - name: layer2
      title: Title of Layer 2
      sources: [cache2]

``layer1`` is a group layer in this case. The WMS service will render ``layer1a`` and ``layer1b`` if you request ``layer1``. Note that ``sources`` is optional if you supply ``layers``. You can still configure ``sources`` for group layers. In this case the group ``sources`` will replace the ``sources`` of the child layers.

``sources``
"""""""""""
A list of data sources for this layer. You can use sources defined in the ``sources`` and ``caches`` section. MapProxy will merge multiple sources from left (bottom) to right (top). 


``min_res``, ``max_res`` or ``min_scale``, ``max_scale``
""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.. NOTE paragraph also in sources/wms section
 
Limit the layer to the given min and max resolution or scale. MapProxy will return a blank image for requests outside of these boundaries. You can use either the resolution or the scale values, missing values will be interpreted as `unlimited`. Resolutions should be in meters per pixel.

The values will also apear in the capabilities documents (i.e. WMS ScaleHint and Min/MaxScaleDenominator).

Pleas read :ref:`scale vs. resolution <scale_resolution>` for some notes on `scale`.


.. ``attribution``
.. """"""""""""""""
.. 
.. Overwrite the system-wide attribution line for this layer.
.. <commit_msg>updated documentation for layer groups<commit_after>Configuration
#############

There are a few different configuration files used by MapProxy.

``mappproxy.yaml``
    This is the main configuration of MapProxy. It configures all aspects of the server:
    Which servers should be started, where comes the data from, what should be cached,
    etc..
    
``seed.yaml``
    This file is the configuration for the ``mapproxy-seed`` tool. See :doc:`seeding documentation <seed>` for more information.

``develop.ini`` or ``config.ini``
    These are the paster configuration files that are used to start MapProxy in development or production mode. See :doc:`deployment documentation <deployment>` for more information.


.. note:: The configuration changed with the 0.9.0 release and you have to update any older configuration. This is a one-time change and further versions will offer backwards-compatibility. Read the :doc:`migration guide <migrate>` for some help.

.. index:: mapproxy.yaml

mapproxy.yaml
=============

The configuration uses the YAML format.

The MapProxy configuration is grouped into six sections, each configures a different aspect of MapProxy. These are the following sections:

- ``globals``:  Internals of MapProxy and default values that are used in the other configuration sections.
  
- ``services``:
  The services MapProxy offers, e.g. WMS or TMS.

- ``sources``: Define where MapProxy can retrieve new data.

- ``caches``: Configure the internal caches.

- ``layers``: Configure the layers that MapProxy offers. Each layer can consist of multiple sources and caches.
  
- ``grids``: Define the grids that MapProxy uses to aligns cached images.
  
The order of the sections is not important, so you can organize it your way.

.. note:: The indentation is significant and shall only contain space characters. Tabulators are **not** permitted for indentation.

.. #################################################################################

.. index:: services

services
--------

Here you can configure which services should be started. The configuration for all services is described in the :doc:`services` documentation.

Here is an example::

  services:
    tms:
    wms:
      md:
        title: MapProxy Example WMS
        contact:
        # [...]

.. #################################################################################
.. index:: layers

layers
------

Here you can define all layers MapProxy should offer. The layer definition is similar to WMS: each layer can have a name and title and you can nest layers to build a layer tree.

Layers should be configured as a list (``-`` in YAML), where each layer configuration is a dictionary (``key: value`` in YAML)

::

  layers:
    - name: layer1
      title: Title of Layer 1
      sources: [cache1, source2]
    - name: layer2
      title: Title of Layer 2
      sources: [cache3]

Each layer contains information about the layer and where the data comes from.

.. _layers_name:

``name``
"""""""""

The name of the layer. You can omit the name for group layers (e.g. layers with ``layers``), in this case the layer is not addressable in WMS and used only for grouping.

.. versionchanged:: 0.9.1

The old syntax to configure each layer as a dictionary with the key as the name is deprecated but still supported.

::

 - mylayer:
    title: My Layer
    source: [mysoruce]

should become

::

 - name: mylayer
   title: My Layer
   source: [mysoruce]


``title``
"""""""""
Readable name of the layer, e.g WMS layer title.


``layers``
""""""""""

.. versionadded:: 0.9.1

Each layer can contain another ``layers`` configuration. You can use this to build group layers and to build a nested layer tree.

For example::

  layers:
    - name: root
      title: Root Layer
      layers:
        - name: layer1
          title: Title of Layer 1
          layers:
            - name: layer1a
              title: Title of Layer 1a
              sources: [source1a]
            - name: layer1b
              title: Title of Layer 1b
              sources: [source1b]
        - name: layer2
          title: Title of Layer 2
          sources: [cache2]

``root`` and ``layer1`` is a group layer in this case. The WMS service will render ``layer1a`` and ``layer1b`` if you request ``layer1``. Note that ``sources`` is optional if you supply ``layers``. You can still configure ``sources`` for group layers. In this case the group ``sources`` will replace the ``sources`` of the child layers.

MapProxy will wrap all layers into an unnamed root layer, if you define multiple layers on the first level.

.. note::
  The old syntax (see ``name`` :ref:`above <layers_name>`) is not supported if you use the nested layer configuration format.

``sources``
"""""""""""
A list of data sources for this layer. You can use sources defined in the ``sources`` and ``caches`` section. MapProxy will merge multiple sources from left (bottom) to right (top). 


``min_res``, ``max_res`` or ``min_scale``, ``max_scale``
""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.. NOTE paragraph also in sources/wms section
 
Limit the layer to the given min and max resolution or scale. MapProxy will return a blank image for requests outside of these boundaries. You can use either the resolution or the scale values, missing values will be interpreted as `unlimited`. Resolutions should be in meters per pixel.

The values will also apear in the capabilities documents (i.e. WMS ScaleHint and Min/MaxScaleDenominator).

Pleas read :ref:`scale vs. resolution <scale_resolution>` for some notes on `scale`.


.. ``attribution``
.. """"""""""""""""
.. 
.. Overwrite the system-wide attribution line for this layer.
.. 
{'fraction_non_alphanumeric': 0.13502417662622024, 'fraction_numerical': 0.005930115865340754, 'mean_word_length': 3.5278810408921935, 'pattern_counts': {'":': 0, '<': 12, '<?xml version=': 0, '>': 12, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2186100', 'n_tokens_mistral': 2987, 'n_tokens_neox': 2886, 'n_words': 1425}