Remove lengthy tutorial from instrument module docstring

The originally written tutorial was a weird and messy combination of a tutorial and a how-to guide, fulfilling neither need. Its contents will later be reworked into another place, with actual thought behind it.

src/resolution_functions/instrument.py

@@ -1,119 +1,6 @@
 """
-This module is the main part of the library, containing the :py:cls:`Instrument` object, which is
-used as a starting point for all functionality, as it represents a physical INS instrument and all
-its data. To get started, you will need to know which instrument and which version of that
-instrument you want to use (for more information about versions, please see :py:cls:`Instrument`),
-all of which can be found in this documentation of programmatically:
-
-```
->>> from resolution_functions import Instrument
->>> Instrument.available_instruments()
-['ARCS', 'CNCS', 'HYSPEC', 'Lagrange', 'LET', 'MAPS', 'MARI', 'MERLIN', 'PANTHER', 'TFXA', 'TOSCA', 'VISION', 'SEQUOIA']
->>> Instrument.available_versions('TOSCA')
-['TFXA', 'TOSCA1', 'TOSCA']
-```
-
-With this information, it is possible to instantiate the relevant instrument:
-
-```
->>> tfxa = Instrument.from_default('TOSCA', 'TFXA')
->>> tfxa.name
-'TOSCA'
->>> tfxa.version
-'TFXA'
->>> tfxa.default_model
-'book'
-```
-
-However, even if we don't know the exact version of an instrument to use, a reasonable default is
-provided (usually the most recent version of that instrument):
-
-```
->>> tosca = Instrument.from_default('TOSCA')
->>> tosca.name
-'TOSCA'
->>> tosca.version
-'TOSCA'
->>> tosca.default_model
-'AbINS'
-```
-
-A lower level API is also provided for advanced use cases (see Advanced Useage).
-
-Once we have the instrument, the next step is to get a model of that instrument. Models describe the
-widening (i.e. resolution) of a given instrument at different energy transfers - there are many
-ways of modeling this behaviour, which is why most instruments have multiple models. For more
-information see :py:mod:`models`. The important part here is that different models include different
-levels of detail and so may require different information. If we know all the information for our
-model (or wish to use the defaults), we can skip to getting the model, but there are programmatic
-ways to query all the various information.
-
-All the things you will need to consider can be obtained in progressive levels by using the
-properties:
-
-```
->>> # Reveal all the models that we can use with the TOSCA instrument
->>> tosca.available_models
-['AbINS', 'book', 'vision']
->>> # Reveal all the models, and which parameters we will need to pass in to each one
->>> tosca.available_models_and_settings
-{'AbINS': [], 'book': ['detector_bank'], 'vision': ['detector_bank']}
->>> # Reveal all the models, which parameters we will need to pass in to each one, and what the options are for each of the parameters
->>> tosca.all_available_models_options
-{'AbINS': {}, 'book': {'detector_bank': ['Backward', 'Forward']}, 'vision': {'detector_bank': ['Backward', 'Forward']}}
-```
-
-It is also possible to make more precise queries:
-
-```
->>> tosca.possible_settings_for_model('book')
-['detector_bank']
->>> tosca.possible_options_for_model('book')
-{'detector_bank': ['Backward', 'Forward']}
->>> tosca.possible_options_for_model_and_setting('book', 'detector_bank')
-['Backward', 'Forward']
->>> tosca.default_option_for_setting('book', 'detector_bank')
-'Backward'
-```
-
-However, the most comphrehensive way to prepare for getting a model, once we knowh which model we
-want, is to get its signature:
-
-```
->>> maps = Instrument.from_default('MAPS', 'MAPS')
->>> signature = maps.get_model_signature('PyChop_fit')
->>> signature
-<Signature (model_name: Optional[str] = 'PyChop_fit', *, chopper_package: Literal['A', 'B', 'S'] = 'A', e_init: Annotated[ForwardRef('Optional[float]'), 'restriction=[0, 2000]'] = 500, chopper_frequency: Annotated[ForwardRef('Optional[int]'), 'restriction=[50, 601, 50]'] = 400, fitting_order: 'Optional[int]' = 4, _)>
-```
-
-This function returns a `inspect.Signature` object from the standard library, which can be further
-queried and contains all the information required for getting the model.
-
-```
->>> # For the MAPS instrument and its PyChop_fit model:
->>> # The first parameter, called model name, is a string with the name of the model. The default is 'PyChop_fit'
->>> signature.parameters['model_name']
-<Parameter "model_name: Optional[str] = 'PyChop_fit'">
->>> # The parameter chopper_package is one of the Fermi chopper options on the MAPS instrument.
->>> # It can be one of 'A', 'B', or 'S'. The default is 'A'
->>> signature.parameters['chopper_package']
-<Parameter "chopper_package: Literal['A', 'B', 'S'] = 'A'">
->>> # The parameter e_init (initial energy) is a float with a default value of 500 meV and the
->>> # restriction that it must be within 0 < e < 2000
->>> signature.parameters['e_init']
-<Parameter "e_init: Annotated[ForwardRef('Optional[float]'), 'restriction=[0, 2000]'] = 500">
->>> # The parameter chopper_frequency specifies the frequency of the Fermi chopper.
->>> # The default is 400 Hz with the restriction that it must be one of the ints between 50 and 600 with a period of 50.
->>> signature.parameters['chopper_frequency']
-<Parameter "chopper_frequency: Annotated[ForwardRef('Optional[int]'), 'restriction=[50, 601, 50]'] = 400">
->>> # The fitting_order parameter is an int with a default of 4, specifying the order of the polynomial used in fitting.
->>> signature.parameters['fitting_order']
->>> # We can also check whether each of the parameters is positional or keyword argument
->>> [parameter.kind for parameter in signature.parameters.values()]
-[<_ParameterKind.POSITIONAL_OR_KEYWORD: 1>, <_ParameterKind.KEYWORD_ONLY: 3>, <_ParameterKind.KEYWORD_ONLY: 3>, <_ParameterKind.KEYWORD_ONLY: 3>, <_ParameterKind.KEYWORD_ONLY: 3>, <_ParameterKind.KEYWORD_ONLY: 3>]
-```
-
-
+The main entry-point to the library - contains the `Instrument` class used for managing all data ond
+computing resolution functions.
 """
 from __future__ import annotations