Merge pull request #103 from jlaehne/rtd_dark

add dark theme support ...

CHANGELOG.md → CHANGELOG.rst

@@ -1,36 +1,49 @@
-# Changelog
+Changelog
+*********
+
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,
+and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 
-## UNRELEASED
-### Changed
-- Add proper handling of variance on Jacobian transformation during axis conversion (eV, invcm)
+UNRELEASED
+==========
+Added
+-----
 - Set up read the docs documentation
+- Add proper handling of variance on Jacobian transformation during axis conversion (eV, invcm)
+
+Changed
+-------
 - Fix error in background dimensions that allows compatibility for updated `map` in HyperSpy (failing integration tests)
 - Fix for links in PyPi
 
-## 2021-11-23 - version 0.1.3
-### Changed
+2021-11-23 - version 0.1.3
+==========================
+Changed
+-------
 - Mentions of the now deleted `non_uniform_axes` branch in HyperSpy updated to `RELEASE_next_minor`
 - Change 'master' to 'main' branch
 - Updated/corrected badges and other things in README.md and other documentation files
 
-## 2021-08-22 - version 0.1.2
-### Added
+2021-08-22 - version 0.1.2
+==========================
+Added
+-----
 - This project now keeps a Changelog
 - Added signal-hierarchy for time-resolved luminescence
 - Added GitHub action for release
 - Created logo
 
-### Changed
+Changed
+-------
 - Consistent black-formatting
 - fixed join_spectra
 - fixed tests
 
-## 
-## 2021-03-26 - version 0.1.0
-### Added
+2021-03-26 - version 0.1.0
+==========================
+Added
+-----
 - The first release, basic functionality implemented
 

CONTRIBUTING.rst

@@ -0,0 +1,92 @@
+Contributing
+************
+
+LumiSpy is meant to be a community maintained project. We welcome contributions
+in the form of bug reports, documentation, code, feature requests, and more.
+In the following we refer to some resources to help you make useful contributions.
+
+Issues
+======
+
+The `issue tracker <https://github.com/lumispy/lumispy/issues>`_ can be used to
+report bugs or propose new features. When reporting a bug, the following is
+useful:
+
+- give a minimal example demonstrating the bug,
+- copy and paste the error traceback.
+
+Pull Requests
+=============
+
+If you want to contribute to the LumiSpy source code, you can send us a
+`pull request <https://github.com/lumispy/lumispy/pulls>`_.
+
+Please refer to the 
+`HyperSpy developer guide <http://hyperspy.org/hyperspy-doc/current/dev_guide/intro.html>`_
+in order to get started and for detailed contributing guidelines.
+
+The `kikuchypy contributors guide <https://kikuchipy.org/en/stable/contributing.html>`_,
+another HyperSpy extension, also is a valuable resource that can get you
+started and provides useful guidelines.
+
+Documentation
+=============
+
+The LumiSpy documentation consists of three elements:
+
+- Docstrings following the `numpy standard
+  <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_
+  that document the functionality of individual methods on `GitHub
+  <https://github.com/LumiSpy/lumispy/tree/main/lumispy/>`_.
+- The `documentation <https://lumispy.org>`_ written using `Sphinx
+  <https://www.sphinx-doc.org/en/master/>`_ and hosted on `Read the Docs
+  <https://lumispy.readthedocs.io/>`_. The source is part of the `GitHub repository
+  <https://github.com/LumiSpy/lumispy/tree/main/doc/source>`_.
+- A set of curated Jupyter notebooks in the `LumiSpy demos repository
+  <https://github.com/lumispy/lumispy-demos>`_ on GitHub that provide tutorials and example
+  workflows.
+
+Improving documentation is always welcome and a good way of starting out to learn the GitHub
+functionality. You can contribute through pull requests to the respective repositories.
+
+Code style
+==========
+
+LumiSpy follows `Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008/>`_
+with `The Black Code style
+<https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html>`_.
+
+For `docstrings <https://www.python.org/dev/peps/pep-0257/>`_, we follow the `numpydoc
+<https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_ standard.
+
+Package imports should be structured into three blocks with blank lines between
+them:
+
+- standard libraries (like ``os`` and ``typing``),
+- third party packages (like ``numpy`` and ``hyperspy``),
+- and finally ``lumispy`` imports.
+
+Writing tests
+=============
+
+All functionality in LumiSpy is tested via the `pytest <https://docs.pytest.org>`_
+framework. The tests reside in the ``test`` directory. Tests are short methods that call
+functions in LumiSpy and compare resulting output values with known answers.
+Please refer to the `HyperSpy development guide
+<https://hyperspy.org/hyperspy-doc/current/dev_guide/testing.html>`_ for further
+information on tests.
+
+Releasing a new version
+=======================
+
+LumiSpy versioning follows `semantic versioning <https://semver.org/spec/v2.0.0.html>`_
+and the version number is therefore a three-part number: MAJOR.MINOR.PATCH.
+Each number will change depending on the type of changes according to the following:
+
+- MAJOR increases when making incompatible API changes,
+- MINOR increases when adding functionality in a backwards compatible manner, and
+- PATCH increases when making backwards compatible bug fixes.
+
+The process to release a new version that is pushed to `PyPI <https://pypi.org>`_ and
+`Conda-Forge <https://conda-forge.org/>`_ is documented in the `Releasing guide
+<https://github.com/LumiSpy/lumispy/blob/main/releasing_guide.md>`_.

README.md

@@ -12,10 +12,10 @@
 
 <img src="https://github.com/LumiSpy/lumispy/raw/main/doc/_static/logo_rec_april21.svg" width="300" alt="LumiSpy">
 
-LumiSpy is an extension Python package for multi-dimensional data analysis 
-provided by the [HyperSpy](https://hyperspy.org) library. It is aimed at helping 
-with the analysis of luminescence spectroscopy data (cathodoluminescence, 
-photoluminescence, electroluminescence, Raman, SNOM).
+LumiSpy is a Python package extending the functionality for multi-dimensional
+data analysis provided by the [HyperSpy](https://hyperspy.org) library. It is
+aimed at helping with the analysis of luminescence spectroscopy data
+(cathodoluminescence, photoluminescence, electroluminescence, Raman, SNOM).
 
 If analysis using LumiSpy forms a part of published work, please consider 
 recognising the code development by citing the project using the [Zenodo-DOI](https://doi.org/10.5281/zenodo.4640445).
@@ -27,8 +27,11 @@ have been curated as a series of Jupyter notebooks that you can work through
 and modify to perform many common analyses. Simply:
 
 1. Download the `lumispy_demos` repository in your desired folder
-2. Load LumiSpy (see [installation guide](https://github.com/LumiSpy/lumispy/blob/main/INSTALLATION.md))
+2. Load LumiSpy (see [installation guide](https://lumispy.readthedocs.io/en/latest/user_guide/installation.html))
 3. In Jupyter lab, navigate to the folder and start using the notebook
 
 Everyone is welcome to contribute. Please read our
-[contributing guidelines](https://github.com/LumiSpy/lumispy/blob/main/.github/CONTRIBUTING.md) and get started!
+[contributing guidelines](https://github.com/LumiSpy/lumispy/blob/main/CONTRIBUTING.rst) and get started!
+
+Development of LumiSpy is documented in the
+[changelog](https://github.com/LumiSpy/lumispy/blob/main/CHANGELOG.rst).