Struggling with sphinx

doc/apidoc/modules.rst

-nabu
-====
-
-.. toctree::
-   :maxdepth: 4
-
-   nabu
-   setup

doc/apidoc/nabu.external.rst

-nabu.external package
-=====================
-
-Module contents
----------------
-
-.. automodule:: nabu.external
-   :members:
-   :undoc-members:
-   :show-inheritance:

doc/apidoc/nabu.imgproc.rst

-nabu.imgproc package
-====================
-
-Module contents
----------------
-
-.. automodule:: nabu.imgproc
-   :members:
-   :undoc-members:
-   :show-inheritance:

doc/apidoc/nabu.interfaces.rst

-nabu.interfaces package
-=======================
-
-Module contents
----------------
-
-.. automodule:: nabu.interfaces
-   :members:
-   :undoc-members:
-   :show-inheritance:

doc/apidoc/nabu.rst

@@ -8,9 +8,6 @@ Subpackages
 
    nabu.cuda
    nabu.distributed
-   nabu.external
-   nabu.imgproc
-   nabu.interfaces
    nabu.io
    nabu.misc
    nabu.opencl

doc/apidoc/setup.rst

-setup module
-============
-
-.. automodule:: setup
-   :members:
-   :undoc-members:
-   :show-inheritance:

doc/conf.py

@@ -77,7 +77,11 @@ def setup(app):
     app.add_config_value('recommonmark_config', {
             'url_resolver': lambda url: github_doc_root + url,
             'auto_toc_tree_section': 'Contents',
+            'enable_math': True,
+            'enable_inline_math': True,
             }, True)
     app.add_transform(AutoStructify)
 
 
+# Document __init__ 
+autoclass_content = 'both'

doc/index.rst

@@ -12,11 +12,10 @@ Welcome to Nabu's documentation!
  
    definitions.md
    ccdprocessing.md
+   phase.md
    nabu_config_file.md
    validators.md
 
-   modules/index.rst
-
    apidoc/nabu.rst
 
 

doc/phase.md

+# Phase Retrieval
+
+Phase Retrieval is the process of extracting the phase shift, induced by the sample on the beam, acquired on the detector. This phase shift is then used to reconstruct a map of the (deviation from unity of the real part of) refractive index through tomographic reconstruction.
+
+Nabu implements the following non-iterative phase retrieval methods.
+
+## Paganin phase retrieval
+
+This phase retrieval method was first described in [[1]](#references).
+
+The implementation [PaganinPhaseRetrieval](apidoc/nabu.preproc.html#nabu.preproc.phase.PaganinPhaseRetrieval) follows the normalization of [[2]](#references) and is compatible with the implementation of [tomopy](https://github.com/tomopy/tomopy).
+
+## Single-Distance CTF phase retrieval
+
+This method, although based on Contrast Transfer Function (CTF) rather than Transport of Intensity (TIE), can also be expressed as a single step "filtering" processing. See for example [[2]](#references).
+
+
+
+## References
+
+[1] D. Paganin Et Al, "Simultaneous phase and amplitude extraction from a single defocused image of a homogeneous object", Journal of Microscopy, Vol 206, Part 1, 2002
+
+[2] Boliang Yu Et Al, "Evaluation of phase retrieval approaches in magnified X-ray phase nano computerized tomography applied to bone tissue," Opt. Express  26, 11110-11124 (2018)
\ No newline at end of file

nabu/preproc/phase.py

@@ -13,7 +13,7 @@ def lmicron_to_db(Lmicron, energy, distance):
     to a value of delta/beta.
 
     Parameters
-    ----------
+    -----------
     Lmicron: float
         Length in microns, values of the parameter "PAGANIN_Lmicron"
         in PyHST2 parameter file.
@@ -22,13 +22,14 @@ def lmicron_to_db(Lmicron, energy, distance):
     distance: float
         Sample-detector distance in microns
 
-    Formula
-    -------
+    Notes
+    --------
     The conversion is done using the formula
 
-    $$
-    L^2 = \pi \lambda D \frac{\delta}{\beta}
-    $$
+       $$
+       L^2 = \\pi \\lambda D \\frac{\\delta}{\\beta}
+       $$
+
     The PyHST2 normalization differs from the one used by other softwares
     like tomopy by a factor $1/(4\pi^2)$
     """
@@ -141,17 +142,19 @@ class PaganinPhaseRetrieval(object):
         The radio is divided, in the Fourier domain, by the original
         "Paganin filter" [1]
 
-        $$
-        F + 1 + \frac{\delta}{\beta} \lambda D \rho |k|^2
-        $$
-        where $k$ is the wave vector, computed as
-
-        $$
-        k_l = \frac{1}{P} (\frac{-1}{2} + \frac{l}{N-1})
-        $$
-        where $P$ is the pixel size, $N$ the number of pixels in one direction,
-        and $l \in [0, N-1]$.
-        The factor $\rho$ is either $\pi$ or $1/(4\pi^2)$
+        .. math::
+
+          F = 1 + \\frac{\\delta}{\\beta} \\lambda D \\rho |k|^2
+
+        where k is the wave vector, computed as
+
+        .. math::
+
+          k_l = \\frac{1}{P} (\\frac{-1}{2} + \\frac{l}{N-1})
+
+        where P is the pixel size, N the number of pixels in one direction,
+        and :math:`l \\in [0, N-1]`.
+        The factor :math:`\\rho` is either :math:`\\pi` or :math:`1/(4\\pi^2)`
         depending on the convention (default is the former).
 
 

setup.py

@@ -42,8 +42,6 @@ def setup_package():
     packages_folders = [
         "cuda",
         "opencl",
-        "external",
-        "interfaces",
         "io",
         "preproc",
         "reconstruction",