Add first draft of docs built with sphinx

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/about.md

@@ -0,0 +1,9 @@
+# About
+
+This package contains data processing, analysis and viewing tools written in Python for several different activities related to inorganic materials chemistry conducted in the NAFUMA-group at the University of Oslo. It is written with the intention of creating a reproducible workflow for documentation purposes, with a focus on interactivity in the data exploration process. 
+
+As of now (08-04-22), the intention is to include tools for XRD-, XANES- and electrochemistry-analysis, however other modules might be added as well.
+
+
+
+

docs/conf.py

@@ -0,0 +1,57 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'NAFUMA'
+copyright = '2022, Rasmus Vester Thøgersen & Halvor Høen Hval'
+author = 'Rasmus Vester Thøgersen & Halvor Høen Hval'
+
+# The full version, including alpha/beta/rc tags
+release = '0.2'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['myst_parser']
+source_suffix = ['.rst', '.md']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+html_sidebars = {'**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']}

docs/index.rst

@@ -0,0 +1,22 @@
+.. NAFUMA documentation master file, created by
+   sphinx-quickstart on Fri Apr  8 15:32:14 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to NAFUMA's documentation!
+==================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   about
+   installation
+   modules/modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.md

@@ -0,0 +1,25 @@
+# Installation
+
+This package is not available on any package repositories, but can be installed by cloning the repository from GitHub and installing via ```pip install``` from the root folder:
+
+```
+$ git clone git@github.com:rasmusthog/nafuma.git
+$ cd nafuma
+$ pip install .
+``` 
+If you are planning on making changes to the code base, you might want to consider installing it in develop-mode in order for changes to take effect without reinstalling by including the ```-e``` flag: 
+
+```
+pip install -e .
+```
+
+As of now (v0.2, 08-04-22), the installer will not install any dependencies. It is recommended that you use `conda` to create an environment from `environment.yml` in the root folder:
+
+```
+$ conda env create --name <your_environment_name_here> --file environment.yml
+$ conda activate <your_environment_name_here>
+```
+
+(remember to also get rid of <> when substituting your environment name).
+
+This should get you up and running!

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/modules/electrochemistry.md

@@ -0,0 +1,3 @@
+# Electrochemistry
+
+This is a placeholder

docs/modules/modules.rst

@@ -0,0 +1,12 @@
+Modules
+==================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+
+   xrd.md
+   xanes.md
+   electrochemistry.md
+
+

docs/modules/xanes.md

@@ -0,0 +1 @@
+# XANES

docs/modules/xrd.md

@@ -0,0 +1,130 @@
+# XRD
+
+This module contains functions to view diffractogram data from several different sources. The Some features include:
+
+- Allows the user to plot the data in wavelength independent parameters (d, 1/d, q, q{math}`^2`, q{math}`^4`), or translated to CuK{math}`\alpha` or MoK{math}`\alpha` allowing comparison between diffractograms obtained with different wavelengths
+- Plotting in interactive mode within Jupyter Notebook using the `ipywidgets`-package allowing real-time change of (certain) parameters
+- Plotting reflection ticks and/or reflection indices from multiple simulated reflection tables (generated by VESTA) for comparison
+- Plotting series of diffractograms in stacked mode (including ability to rotate the view for a 3D-view) or as a heatmap
+
+
+
+## 1 Compatible file formats
+
+The module is partially built as a wrapper around [pyFAI](https://github.com/silx-kit/pyFAI) (Fast Azimuthal Integrator) developed at the ESRF for integrating 2D diffractograms from the detectors they have. Given a suitable calibration file (`.poni`), the XRD-module will automatically integrate any file pyFAI can integrate. Upon running in interactive mode, the integration is only done once, but it is advised to perform integration of many diffractograms in a separate processing step and saving the results as `.xy`-files, as the integration will run again each time the function is called.
+
+In addition to this, it can also read the `.brml`-files produced by Bruker-instruments in the RECX-lab at the University of Oslo.
+
+## 2 Basic usage
+
+Plotting diffractograms is done by calling the `xrd.plot.plot_diffractogram()`-function, which takes two dictionaries as arguments: `data`, containing all data specific information and `options` which allows customisation of a range of different parameters. The `options`-argument is optional, and the function will contains a bunch of default values to make an as good plot as possible to begin with.
+
+**Example #1: Single diffractogram**
+
+```py
+import nafuma.xrd as xrd
+
+data = {
+    'path': 'path/to/data/diffractogram.brml'
+}
+
+options = {
+    'reflections_data': [
+        {'path': 'reflections_phase_1.txt', 'min_alpha': 0.1, 'reflection_indices': 4, 'label': 'Phase 1', 'text_colour': 'black'},
+	{'path': 'reflections_phase_2.txt', 'min_alpha': 0.1, 'reflections_indices': 4, 'label': 'Phase 2', 'text_colour': 'red'}
+    ],
+    'hide_y_ticklabels': True,
+    'hide_y_ticks': True
+} 
+
+
+diff, fig, ax = xrd.plot.plot_diffractogram(data=data, options=options)
+```
+
+The return value `diff` is a list containing one `pandas.DataFrame` per diffractogram passed, in the above example only one. `fig` and `ax` are `matplotlib.pyplot.Figure`- and `matplotlib.pyplot.Axes`-objects, respectively.
+
+**Example #2: 2D diffractogram from ESRF requiring integration**
+
+```py
+import nafuma.xrd as xrd
+
+data = {
+    'path': 'path/to/data/2d_diffractogram.edf',
+    'calibrant': 'path/to/calibrant/calibrant.poni',
+    'nbins': 3000
+}
+
+diff, _ = xrd.plot.plot_diffractogram(data=data, options=options)
+```
+
+In this case we did not specify any options and will thus only use default values, and we stored both `fig` and `ax` in the variable `_` as we do not intend to use these.
+
+**Example #3: Plotting with interactive mode**
+
+This will can be done within a Jupyter Notebook, and will allow the user to tweak certain parameters real-time instead of having to recall the function every time.
+
+```py
+import nafuma.xrd as xrd
+
+data = {
+    'path': 'path/to/data/diffractogram.brml'
+}
+
+options = {
+    'interactive': True
+}
+
+
+diff, _ = xrd.plot.plot_diffractogram(data=data, options=options)
+```
+
+**Example #4: Plotting multiple diffractograms as stacked plots**
+
+Instead of passing just a string, you can pass a lsit of filenames. This will be plotted sequentially, with offsets, if desired (`offset_x` and `offset_y`). Default values of `offset_y` is 1 if less than 10 diffractograms have been passed, and 0.1 if more than 10 diffractograms are passed. When plotting series data (e.g. from *in situ* or *operando* measurements), a smaller offset is suitable. Keep in mind that these values only makes sense when the diffractograms are normalised (`'normalise': True`) - if not, the default offsets will be way too small to be noticeable.
+
+```py
+import nafuma.xrd as xrd
+
+data = {
+    'path': ['path/to/data/diffractogram_1.brml', 'path/to/data/diffractogram_2.brml']
+}
+
+
+options = {
+    'offset_y': 0.1,
+    'offset_x': 0.05,
+}
+
+
+diff, _ = xrd.plot.plot_diffractogram(data=data, options=options)
+```
+
+
+**Example #5: Plotting series data as heatmap**
+
+This differs very little from above, except that heatmaps are probably nonesense if not used on series data, and that you don't want offset in heatmaps. 
+
+```py
+import nafuma.xrd as xrd
+
+list_of_data = ['data_1.brml', 'data_2.brml'. ...., 'data_n.brml']
+
+data = {
+    'path': lists_of_data
+}
+
+
+options = {
+    'heatmap': True
+}
+
+
+diff, _ = xrd.plot.plot_diffractogram(data=data, options=options)
+```
+
+
+
+
+
+
+