Overhaul of the DeerLab documentation website for v0.14.0 (#234)

* implement penalty system for models

* refactor addpenalty function, fix one warning in ICC functional

* dipolarmodel: implement compactness and smoothness penalties on P(r)

* tests: avoid model modification by tests

* snlls: correct covariance estimation in the presence of frozen parameters

* dipolarkernel: minor edits in docstring

* add docstrings to experiment-specific dipolar models

* adapt beginners_guide to new interface (WIP)

* implement regularization penalty for models

* expand model print function

* expand model print function

* work on getting_started docs (WIP)

* pass penalties to the fit function instead of incorporating to the model

* overhaul of the Sphinx theme and web design

- removes Sphinx version dependency

* fix error in test

* overhaul of documentation (WIP)

- add modelling guide
- add fitting guide 
- reorder old sections 
- improve automatization of reference pages
- further style edits  
- many minor edits

* overhaul of documentation (WIP)

- rewrite uncertainty guide 
- improve landing page 
- lots of minor edits
- more styling

* overhaul of documentation (WIP)

- better automatize the API reference 
- edit/update the dipolar EPR guide 
-  add missing end edit many docstrings

* remove the _autosummary folder from version control

* adapt packages required workflows

* remove seaborn dependency

* streamline the changelog

* minor edits

* finish up the getting started guide for dipolar EPR

* fix and edit some models

* remove the old markdown changelog

* remove RTD theme remains in conf.py

* add missing package to workflow

* workflows: update the sphinx version

* fix error in test

* cleanup conf.py and properly document new lines

* cleanup unused docsrc files

* docs: add section to fitting guide

* document some of the utils functions

* document some of the utils functions

* add back example plots to dd_models

* fix all Sphinx warnings during build

* remove twitter icon

* automate table string formatting, improve model printout

* add summary  table printout for fit results, improve guides

* fix URLs in landing page

* fix bugs related to new _print_fitresults() function

* minor edits and fixes in examples

* split and restructure user-guide sections

* further clean up structure

* fix size and padding of images in model references 

other minor edits

Co-authored-by: Stefan Stoll <[email protected]>

Author: luisfabib

.github/workflows/deploy_ghpages.yml

@@ -26,13 +26,14 @@ jobs:
     - name: Install dependencies
       run: |
            python -m pip install --upgrade pip
-           python -m pip install sphinx_rtd_theme
+           python -m pip install pydata-sphinx-theme
            python -m pip install numpydoc
            python -m pip install sphinx-gallery
            python -m pip install sphinxcontrib-httpdomain
            python -m pip install sphinxcontrib-ghcontributors
-           python -m pip install m2r2
-           python -m pip install sphinx==1.8.4
+           python -m pip install sphinx-issues
+           python -m pip install sphinx-copybutton  
+           python -m pip install sphinx
            sudo apt install texlive-extra-utils
            sudo apt-get install texlive-latex-extra
            python -m pip install .

.github/workflows/docs_PR.yml

@@ -29,13 +29,14 @@ jobs:
     - name: Install dependencies
       run: |
            python -m pip install --upgrade pip
-           python -m pip install sphinx_rtd_theme
+           python -m pip install pydata-sphinx-theme
            python -m pip install numpydoc
            python -m pip install sphinx-gallery
            python -m pip install sphinxcontrib-httpdomain
            python -m pip install sphinxcontrib-ghcontributors
-           python -m pip install m2r2
-           python -m pip install sphinx==1.8.4
+           python -m pip install sphinx-copybutton  
+           python -m pip install sphinx-issues
+           python -m pip install sphinx
            sudo apt install texlive-extra-utils
            sudo apt-get install texlive-latex-extra
            python -m pip install .

.gitignore

@@ -24,6 +24,7 @@ dist/
 build/
 .debugging.py
 multidocs/**/*
+docsrc/source/_autosummary/**/*
 docsrc/source/auto_examples/**/*
 docsrc/plot_directive/
 docsrc/source/_build/

CHANGELOG.md

@@ -2,12 +2,12 @@
 from .dd_models import *
 from .bg_models import *
 from .ex_models import *
-from .model import Model, link, lincombine, merge, relate, fit
+from .model import Model, Penalty, Parameter, link, lincombine, merge, relate, fit
 from .deerload import deerload
 from .selregparam import selregparam
 from .dipolarkernel import dipolarkernel
 from .dipolarbackground import dipolarbackground
-from .dipolarmodel import dipolarmodel, dipolarpenalty, ex_4pdeer,ex_3pdeer,ex_5pdeer
+from .dipolarmodel import dipolarmodel,ExperimentInfo, dipolarpenalty, ex_4pdeer,ex_3pdeer,ex_5pdeer
 from .solvers import snlls
 from .regoperator import regoperator
 from .correctphase import correctphase

deerlab/__init__.py

@@ -8,7 +8,7 @@
 import scipy as scp
 from numpy import pi
 import inspect
-from deerlab.utils import load_exvolume_redfactor
+from deerlab.utils import load_exvolume_redfactor,formatted_table
 from deerlab.model import Model
 
 # Natural constants
@@ -57,31 +57,34 @@ def _docstring(model,notes):
     Notes
     -----
 
-    **Parameter List**
-
-    ============ ========= ========== =========== ========== ==========================
-        Name       Lower     Upper      Type        Units     Description  
-    ============ ========= ========== =========== ========== ==========================""")
+    **Parameter Table**
+    """) 
+    string += '\n'
+    string += '\n'
+    table = []
+    table.append(['Name','Lower','Upper','Type','Frozen','Units','Description'])  
     for n,paramname in enumerate(model._parameter_list(order='vector')): 
-        string += f'\n   {paramname:7s}'
-        string += f'     {getattr(model,paramname).lb:5.3g}'
-        string += f'     {getattr(model,paramname).ub:5.3g}'
-        string += f'      {"linear" if getattr(model,paramname).linear else "nonlin"}'
-        string += f'       {str(getattr(model,paramname).units):6s}'
-        string += f'   {str(getattr(model,paramname).description):s}'
-    string += f'\n============ ========= ========== =========== ========== =========================='
+        param_str = f'``{paramname}``'
+        lb_str = f'{np.atleast_1d(getattr(model,paramname).lb)[0]:5.3g}'
+        ub_str = f'{np.atleast_1d(getattr(model,paramname).ub)[0]:5.3g}'
+        linear_str = "linear" if np.all(getattr(model,paramname).linear) else "nonlin"
+        frozen_str = "Yes" if np.all(getattr(model,paramname).frozen) else "No"
+        units_str = str(getattr(model,paramname).units)
+        desc_str = str(getattr(model,paramname).description)
+        table.append([param_str,lb_str,ub_str,linear_str,frozen_str,units_str,desc_str])
+    string += formatted_table(table)
+    string += f'\n{notes}'
 
     string += f'\n{notes}'
 
-    model.__doc__ = string
-    return model
+    return string
 #---------------------------------------------------------------------------------------
 
 #=======================================================================================
 #                                     bg_hom3d
 #=======================================================================================
 notes = r"""
-**Model:**
+**Model**
 
 This model describes the inter-molecular interaction of one observer spin with a 3D homogenous distribution of spins of concentration `c_s`
 
@@ -120,7 +123,7 @@ def _hom3d_fcn(t,conc,lam):
 #                                     bg_hom3dex
 #=======================================================================================
 notes = r"""
-**Model:**
+**Model**
 
 .. image:: ../images/model_scheme_bg_hom3dex.png
    :width: 350px
@@ -178,7 +181,7 @@ def _hom3dex(t,conc,rexcl,lam):
 #                                     bg_homfractal
 #=======================================================================================
 notes = r"""
-**Model:**
+**Model**
 
 This implements the background due to a homogeneous distribution of spins in a d-dimensional space, with d-dimensional spin concentration ``c_d``.
 """  
@@ -217,7 +220,7 @@ def _homfractal(t,fconc,fdim,lam):
 #                                     bg_exp
 #=======================================================================================
 notes= r"""
-**Model:**
+**Model**
 
 .. math::
 
@@ -242,7 +245,7 @@ def _exp(t,decay):
 #                                     bg_strexp
 #=======================================================================================
 notes = r"""
-**Model:**
+**Model**
 
 .. math::
 
@@ -268,7 +271,7 @@ def _strexp(t,decay,stretch):
 #                                     bg_prodstrexp
 #=======================================================================================
 notes = r"""
-**Model:**
+**Model**
 
 :math:`B(t) = \exp\left(-\kappa_1 \vert t \vert^{d_1}\right) \exp\left(-\kappa_2 \vert t\vert^{d_2}\right)`
 """  
@@ -293,7 +296,7 @@ def _prodstrexp(t,decay1,stretch1,decay2,stretch2):
 #                                     bg_sumstrexp
 #=======================================================================================
 notes = r"""
-**Model:**
+**Model**
 
 :math:`B(t) = A_1\exp \left(-\kappa_1 \vert t \vert^{d_1}\right) + (1-A_1)\exp\left(-\kappa_2 \vert t \vert^{d_2}\right)`
 """ 
@@ -318,7 +321,7 @@ def _sumstrexp(t,decay1,stretch1,weight1,decay2,stretch2):
 #                                     bg_poly1
 #=======================================================================================
 notes =  r"""
-**Model:**
+**Model**
 
 :math:`B(t) = p_0 + p_1 t`
 """  
@@ -339,7 +342,7 @@ def _poly1(t,p0,p1):
 #                                     bg_poly2
 #=======================================================================================
 notes =  r"""
-**Model:**
+**Model**
 
 :math:`B(t) = p_0 + p_1 t + p_2 t^2`
 """  
@@ -360,7 +363,7 @@ def _poly2(t,p0,p1,p2):
 #                                     bg_poly2
 #=======================================================================================
 notes =  r"""
-**Model:**
+**Model**
 
 :math:`B(t) = p_0 + p_1 t + p_2 t^2 + p_3 t^3`
 """  

deerlab/bg_models.py

@@ -54,10 +54,13 @@ def __getattr__(self, name):
             return self[name]
         except KeyError:
             raise AttributeError(name)
-
+    
     __setattr__ = dict.__setitem__
     __delattr__ = dict.__delitem__
 
+    def __str__(self): 
+        return self._summary
+
     def __repr__(self):
         if self.keys():
             m = max(map(len, list(self.keys()))) + 1