docs: improvements and fixes

src/ramanchada2/__init__.py

@@ -2,27 +2,24 @@
 
 
 """
-# Ramanchada2
-
-## Purpose
+# Purpose
 `ramanchada2` software package is meant to fill the gap between the theoretical
 Raman analysis and the experimental Raman spectroscopy by providing means to
 compare data of different origin. The software is in early development stage
 but still able to solve practical problems.
 
-## Features
-
+# Features
 
-### Read simulated data
-Process simulated data by [VASP] and [CRYSTAL] and provide same interface.
+## Read simulated data
+Process simulated data by [VASP][] and [CRYSTAL][] and provide same interface.
 CRYSTAL data contain intensities for multiple orientations -- laser beam
 incidents perpendicularly or parallelly to the observation and information
 for mono-crystals. VASP data provide data only for poly-crystals but in
 different format. So the perpendicular and parallel intensities are calculated
-by an implemented [algorithm](https://doi.org/10.1103/PhysRevB.54.7830).
+by an implemented [algorithm][].
 
-### Models
-[LMFIT] theoretical models can be build by spectral information obtained by
+## Models
+[LMFIT][] theoretical models can be build by spectral information obtained by
 simulations or by provided by the user. These models can be fit to experimental
 data, providing calibration information. At poor initial calibration the minimisation
 procedure naturally fails. An iterative procedure aiming to solve this problem
@@ -32,20 +29,20 @@
 the second iteration. In few iterations the algorithm is able to fit to the original
 experimental data. This idea is implemented and is at proof-of-concept level.
 
-### Generate spectra
+## Generate spectra
 Spectra can be generated by the theoretical models. Random Poissonian noise and
 artificial random-generated baseline can be added to the generated spectra, making
 them convenient tools to test new methods for analysis.
 
-### Spectrum manipulation
+## Spectrum manipulation
 A number of filters can be applied to spectra (experimental and generated).
 Scaling on both x and y axes is possible. Scaling could be linear or arbitrary
 user defined function. A convolution is possible with set of predefined functions
 as well as user defined model.
 
-## Concept
+# Concept
 The code is object oriented, written in python. Main elements are Spectrum and
-theoretical models. Theoretical models are based on [LMFIT] library, while
+theoretical models. Theoretical models are based on LMFIT library, while
 Spectrum is a custom made class. Spectrum object contains data for x and y axes
 and metadata coming from experimental files or other sources. It is planned
 to add information about the uncertainties in x and y. All filters and manipulation
@@ -54,39 +51,42 @@
 unchanged. Additionally, Spectrum has information about its history -- the sequence
 of applied filters.
 
-## File formats
-### `.cha` vs [USID]/[NSID]
-`ramanchada`(1) software package introduced `.cha` file format, which is a [HDF5]
-with a specific architecture. Two spectroscopy specific file formats -- [USID] and
-[NSID] -- were considered as successors of `.cha`. [USID] and [NSID] are provided
-by [pycroscopy] package as an extension of [HDF5]. Several jupyter notebooks were
+# File formats
+
+## `.cha` vs USID/NSID
+[ramanchada][] software package introduced `.cha` file format, which is an [HDF5][]
+with a specific architecture. Two spectroscopy specific file formats -- [USID][] and
+[NSID][] -- were considered as successors of `.cha`. USID and NSID are provided
+by [pycroscopy][] package as an extension of HDF5. Several jupyter notebooks were
 created in order to assess the advantages and disadvantages of such a change. These
 file formats are designed to handle multidimensional spectral data, keeping track
 of the modifications. These file formats does not provide big advantage in our case,
-so currently `ramanchada2` supports `.cha` file format and does not support [USID]
-or [NSID].
+so currently `ramanchada2` supports `.cha` file format and does not support USID
+or NSID.
 
-### Cache
+## Cache
 The concept to keep previous variants of data is employed in `ramanchada2`. If
 configured so, the software saves the data for all Spectrum instances to a
 tree-organized `.cha` file. When a particular chain of operations is requested
 by the user, the software checks if the final result is present in the cache file,
 if so it is provided, otherwise the software checks for its parent. When a parent
 or some of the grand parents are present, they are taken as a starting point and
 the needed steps are applied to provide the final result. The current implementation
-uses [h5py] library to access local hdf files. It is foreseen to have implementation
-with [h5pyd] that support network operations.
+uses [h5py][] library to access local hdf files. It is foreseen to have implementation
+with [h5pyd][] that support network operations.
 
 
-[VASP]: https://www.vasp.at/
 [CRYSTAL]: https://www.crystal.unito.it/index.php
-[LMFIT]: https://lmfit.github.io/lmfit-py/index.html
 [HDF5]: https://hdfgroup.org/
+[LMFIT]: https://lmfit.github.io/lmfit-py/index.html
+[NSID]: https://pycroscopy.github.io/pyNSID
+[USID]: https://pycroscopy.github.io/USID
+[VASP]: https://www.vasp.at/
+[algorithm]: https://doi.org/10.1103/PhysRevB.54.7830
 [h5py]: https://h5py.org/
 [h5pyd]: https://github.com/HDFGroup/h5pyd
 [pycroscopy]: https://pycroscopy.github.io/pycroscopy/
-[USID]: https://pycroscopy.github.io/USID
-[NSID]: https://pycroscopy.github.io/pyNSID
+[ramanchada]: https://github.com/h2020charisma/ramanchada
 """
 
 from __future__ import annotations