docs: include setting up custom schemes

docs/index.rst

@@ -22,6 +22,7 @@ scholarly communication.
 Features
 ========
 
+- Addition of custom schemes supporting all features of predefined schemes
 - Validation and normalization of persistent identifiers.
 - Detection of persistent identifier scheme.
 - Generation of resolving links for persistent identifiers.
@@ -46,11 +47,18 @@ API
 .. automodule:: idutils
    :members: is_isbn10, is_isbn13, is_isbn, is_issn, is_istc, is_doi, is_handle, is_ean8, is_ean13, is_ean, is_isni, is_orcid, is_purl, is_url, is_lsid, is_urn, is_ads, is_arxiv_post_2007, is_arxiv_pre_2007, is_arxiv, is_pmid, is_pmcid, is_gnd, is_sra, is_bioproject, is_biosample, is_ensembl, is_uniprot, is_refseq, is_genome, is_geo, is_arrayexpress_array, is_arrayexpress_experiment, detect_identifier_schemes, normalize_doi, normalize_handle, normalize_ads, normalize_orcid, normalize_gnd, normalize_pmid, normalize_arxiv, normalize_pid, to_url
 
-
 .. include:: ../CHANGES.rst
 
 .. include:: ../CONTRIBUTING.rst
 
+
+How to add your own schemes
+===========================
+
+.. automodule:: idutils.ext
+   :members:
+
+
 License
 =======
 

idutils/__init__.py

@@ -14,42 +14,7 @@
 # granted to it by virtue of its status as an Intergovernmental Organization
 # or submit itself to any jurisdiction.
 
-"""Small library for persistent identifiers used in scholarly communication.
-
-Setting up custom schemes
--------------------------
-In order to define your own custom schemes you can use the following entrypoint to
-register them
-
-.. code-block:: python
-
-    [options.entry_points]
-    idutils.custom_schemes =
-        my_new_scheme = my_module.get_scheme_config_func
-
-The entry point ``'my_new_scheme = my_module.get_scheme_config_func'`` defines an entry
-point named ``my_new_scheme`` pointing to the function ``my_module.get_scheme_config_func``
-which returns the config for your new registered scheme.
-
-That function must return a dictionary with the following format:
-
-.. code-block:: python
-
-    def get_scheme_config_func():
-        return {
-            # See examples in `idutils.validators` file.
-            "validator": lambda value: True else False,
-            # Used in `idutils.normalizers.normalize_pid` function.
-            "normalizer": lambda value: normalized_value,
-            # See examples in `idutils.detectors.IDUTILS_SCHEME_FILTER` config.
-            "filter": ["list_of_schemes_to_filter_out"],
-            # Used in `idutils.normalizers.to_url` function.
-            "url_generator": lambda scheme, normalized_pid: "normalized_url",
-        }
-
-Each key is optional and if not provided a default value is defined in
-`idutils.ext._set_default_custom_scheme_config()` function.
-"""
+"""Small library for persistent identifiers used in scholarly communication."""
 
 import importlib
 import pkgutil

idutils/ext.py

@@ -11,7 +11,42 @@
 # granted to it by virtue of its status as an Intergovernmental Organization
 # or submit itself to any jurisdiction.
 
-"""Invenio IDUtils module for managing persistent identifiers used in scholarly communication."""
+"""Extension class to collect and register new schemes via entrypoints.
+
+In order to define your own custom schemes you can use the following entrypoint to
+register them
+
+.. code-block:: python
+
+    [options.entry_points]
+    idutils.custom_schemes =
+        my_new_scheme = my_module.get_scheme_config_func
+
+The entry point ``'my_new_scheme = my_module.get_scheme_config_func'`` defines an entry
+point named ``my_new_scheme`` pointing to the function ``my_module.get_scheme_config_func``
+which returns the config for your new registered scheme.
+
+That function must return a dictionary with the following format:
+
+.. code-block:: python
+
+    def get_scheme_config_func():
+        return {
+            # See examples in `idutils.validators` file.
+            "validator": lambda value: True else False,
+            # Used in `idutils.normalizers.normalize_pid` function.
+            "normalizer": lambda value: normalized_value,
+            # See examples in `idutils.detectors.IDUTILS_SCHEME_FILTER` config.
+            "filter": ["list_of_schemes_to_filter_out"],
+            # Used in `idutils.normalizers.to_url` function.
+            "url_generator": lambda scheme, normalized_pid: "normalized_url",
+        }
+
+Each key is optional and if not provided a default value is defined in
+`idutils.ext._set_default_custom_scheme_config()` function.
+
+Note: You can only add new schemes but not override existing ones.
+"""
 
 from threading import Lock
 
@@ -60,18 +95,18 @@ def custom_schemes(self):
         """Return the registered custom registered schemes.
 
         Each item of the registry is of the format:
-        {
-            "custom_scheme": {
-                # See examples in `idutils.validators` file.
-                "validator": lambda value: True else False,
-                # Used in `idutils.normalizers.normalize_pid` function.
-                "normalizer": lambda value: normalized_value,
-                # See examples in `idutils.detectors.IDUTILS_SCHEME_FILTER` config.
-                "filter": ["list_of_schemes_to_filter_out"],
-                # Used in `idutils.normalizers.to_url` function.
-                "url_generator": lambda scheme, normalized_pid: "normalized_url",
+            {
+                "custom_scheme": {
+                    # See examples in `idutils.validators` file.
+                    "validator": lambda value: True else False,
+                    # Used in `idutils.normalizers.normalize_pid` function.
+                    "normalizer": lambda value: normalized_value,
+                    # See examples in `idutils.detectors.IDUTILS_SCHEME_FILTER` config.
+                    "filter": ["list_of_schemes_to_filter_out"],
+                    # Used in `idutils.normalizers.to_url` function.
+                    "url_generator": lambda scheme, normalized_pid: "normalized_url"
+                }
             }
-        }
         """
         return self._custom_schemes_registry