Repository: gammapy/gammapy

Issue:
Expose undocumented new features from v1.1 and v1.0
Several features have been introduced in v1.0 and v1.1 but lack proper documentation. Ideally this should sorted for 1.2.

The main features are
- [x] `gammapy.estimators.resample_energy_edges` : the question of providing minimum number of counts of significance per bin comes regularly. This could be exposed in several places (e.g. in an how-to and in some tutorials)
- [x] `select_nested_models` can be demonstrated for different use cases, e.g. source TS estimation and/or spectral feature detection
- [x] observation clustering should also be presented in its own notebook.
- [x] we should expose the `DatasetsMaker`
- [x] we could demonstrate using different spectral normalization models for `FoVBackgroundModel`

Are there others? 

I propose we discuss possible presentations in this issue's discussion


Discussion:
I can create the tutorial for the observation clustering as this is something I have been utilising recently
I can implement the different spectral normalisation models for the `FoVBackgroundModel`. 
I think this requires some discussion. 

Initially I would say it makes sense to adapt the doc [here](https://docs.gammapy.org/1.1/user-guide/makers/fov.html), such that a `PowerLawNormSpectralModel` is added into the `FoVBackgroundModel` and the `tilt` and `norm` are allowed to be free. And even [here](https://docs.gammapy.org/1.1/tutorials/analysis-3d/analysis_3d.html). This is quite a typical process when using this model. 

Then I would suggest adding a separate tutorial which shows this and also the implementation of a more complex spectral model (i.e. the `PiecewiseNormSpectralModel`) along with how these affect the background, and how to show the various parameters of the background. 
For the `gammapy.estimators.resample_energy_edges` I would say that it would definitely be useful to expose this in a spectral dataset tutorial and in the HowTo (seeing as it is a common thing to do)
For `select_nested_models` it is possible that @QRemy already has some scripts doing this, as per #4216 ?
The `DatasetsMaker` is already exposed in the docs in makers [here](https://docs.gammapy.org/1.1/tutorials/api/makers.html), however, we could expose it in a tutorial as well i.e. [here](https://docs.gammapy.org/1.1/tutorials/analysis-1d/extended_source_spectral_analysis.html#perform-the-data-reduction-loop). 
We cannot expose it in tutorials which print out information throughout the data reduction loop i.e. [here](https://docs.gammapy.org/1.1/tutorials/starting/analysis_2.html#perform-the-data-reduction-loop)

Resolving patch:
diff --git a/gammapy/modeling/selection.py b/gammapy/modeling/selection.py
--- a/gammapy/modeling/selection.py
+++ b/gammapy/modeling/selection.py
@@ -151,6 +151,42 @@ def select_nested_models(
             * "ts" : fit statistic difference with null hypothesis
             * "fit_results" : results for the best fit
             * "fit_results_null" : fit results for the null hypothesis
+
+    Examples
+    --------
+    .. testcode::
+
+        from gammapy.modeling.selection import select_nested_models
+        from gammapy.datasets import Datasets, SpectrumDatasetOnOff
+        from gammapy.modeling.models import SkyModel
+
+        # Test if cutoff is significant
+        dataset = SpectrumDatasetOnOff.read("$GAMMAPY_DATA/joint-crab/spectra/hess/pha_obs23523.fits")
+        datasets = Datasets(dataset)
+        model = SkyModel.create(spectral_model="ecpl", spatial_model="point", name='hess')
+        datasets.models = model
+        result = select_nested_models(datasets,
+                                      parameters=[model.spectral_model.lambda_],
+                                      null_values=[0],
+                                      )
+
+        # Test if source is significant
+        filename = "$GAMMAPY_DATA/fermi-3fhl-crab/Fermi-LAT-3FHL_datasets.yaml"
+        filename_models = "$GAMMAPY_DATA/fermi-3fhl-crab/Fermi-LAT-3FHL_models.yaml"
+        fermi_datasets = Datasets.read(filename=filename, filename_models=filename_models)
+        model = fermi_datasets.models["Crab Nebula"]
+        # Number of parameters previously fit for the source of interest
+        n_free_parameters = len(model.parameters.free_parameters)
+        # Freeze spatial parameters to ensure another weaker source does not move from its position
+        # to replace the source of interest during the null hypothesis test.
+        # (with all parameters free you test N vs. N+1 models and not the detection of a specific source.)
+        fermi_datasets.models.freeze(model_type='spatial')
+        results = select_nested_models(fermi_datasets,
+                                      parameters=[model.spectral_model.amplitude],
+                                      null_values=[0],
+                                      n_free_parameters=n_free_parameters,
+                                      n_sigma=4,
+                                      )
     """
     test = TestStatisticNested(parameters, null_values, n_sigma, n_free_parameters, fit)
     return test.run(datasets)
diff --git a/gammapy/utils/parallel.py b/gammapy/utils/parallel.py
--- a/gammapy/utils/parallel.py
+++ b/gammapy/utils/parallel.py
@@ -106,6 +106,7 @@ class multiprocessing_manager:
     Examples
     --------
     ::
+
         import gammapy.utils.parallel as parallel
         from gammapy.estimators import FluxPointsEstimator
 


Test patch: