xarpes 0.4.0__tar.gz → 0.5.0__tar.gz

{xarpes-0.4.0 → xarpes-0.5.0}/.gitignore

@@ -81,6 +81,10 @@ target/
 .ipynb_checkpoints
 *.ipynb
 
+# --- allow tracked notebooks in documentation ---
+!doc/notebooks/
+!doc/notebooks/*.ipynb
+
 # IPython
 profile_default/
 ipython_config.py
@@ -173,5 +177,7 @@ cython_debug/
 # VS Code
 .vscode/
 
-# Ignore Rmd2py.py script in examples folder
-examples/Rmd2py.py
+# Ignore conversion scripts if placed in examples folder
+examples/Rmd2ipynb.py
+examples/ipynb2Rmd2py.py
+examples/Rmd2py.py

{xarpes-0.4.0 → xarpes-0.5.0}/PKG-INFO

@@ -1,13 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.1
 Name: xarpes
-Version: 0.4.0
+Version: 0.5.0
 Summary: Extraction from angle resolved photoemission spectra
 Author: xARPES Developers
 Requires-Python: >=3.7.0
 Description-Content-Type: text/markdown
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Programming Language :: Python :: 3
-License-File: LICENSE
 Requires-Dist: igor2>=0.5.8
 Requires-Dist: jupyterlab
 Requires-Dist: jupytext
@@ -33,7 +32,9 @@ This project is currently undergoing **beta testing**. Some of the functionaliti
 
 # Contributing
 
-Contributions to the code are most welcome. xARPES is intended to co-develop alongside the increasing complexity of experimental ARPES data sets. Contributions can be made by forking the code and creating a pull request. Importing of file formats from different beamlines is particularly encouraged. Files useful for developers can be found in `/dev_tools`, such as the `Rmd2py.py` script for the development of examples.
+Contributions to the code are most welcome. xARPES is intended to co-develop alongside the increasing complexity of experimental ARPES data sets. Contributions can be made by forking the code and creating a pull request. Importing of file formats from different beamlines is particularly encouraged. For development of the examples, the following scripts in `/dev_tools` could be useful:
+- The `Rmd2ipynb.py` file, to generate the `.ipynb` from which the examples can conveniently be developed; to be executed after cloning/pulling updated `.Rmd` and `.py` files, or if you prefer developing with `.Rmd` files.
+- The `ipynb2Rmd2py.py` file, to synchronise the `.Rmd` and `.py` files from the `.ipynb` file; to be executed right before pushing modifications to the repository. Note that this script resets some metadata in the `.Rmd` to prevent the tracking of their changes due to local virtual environments, etc.
 
 # Installation
 

{xarpes-0.4.0 → xarpes-0.5.0}/README.md

@@ -10,7 +10,9 @@ This project is currently undergoing **beta testing**. Some of the functionaliti
 
 # Contributing
 
-Contributions to the code are most welcome. xARPES is intended to co-develop alongside the increasing complexity of experimental ARPES data sets. Contributions can be made by forking the code and creating a pull request. Importing of file formats from different beamlines is particularly encouraged. Files useful for developers can be found in `/dev_tools`, such as the `Rmd2py.py` script for the development of examples.
+Contributions to the code are most welcome. xARPES is intended to co-develop alongside the increasing complexity of experimental ARPES data sets. Contributions can be made by forking the code and creating a pull request. Importing of file formats from different beamlines is particularly encouraged. For development of the examples, the following scripts in `/dev_tools` could be useful:
+- The `Rmd2ipynb.py` file, to generate the `.ipynb` from which the examples can conveniently be developed; to be executed after cloning/pulling updated `.Rmd` and `.py` files, or if you prefer developing with `.Rmd` files.
+- The `ipynb2Rmd2py.py` file, to synchronise the `.Rmd` and `.py` files from the `.ipynb` file; to be executed right before pushing modifications to the repository. Note that this script resets some metadata in the `.Rmd` to prevent the tracking of their changes due to local virtual environments, etc.
 
 # Installation
 

xarpes-0.5.0/dev_tools/Rmd2ipynb.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""
+Generate .ipynb notebooks from .Rmd files using Jupytext.
+
+- For every .Rmd (excluding hidden folders and .ipynb_checkpoints),
+  create or overwrite a sibling <notebook>.ipynb using Jupytext.
+
+Dependencies:
+    pip install jupytext
+
+Usage:
+    Place Rmd2ipynb.py in the /examples directory, where it is .gitignored.
+    $ python Rmd2ipynb.py  # run from anywhere; it operates where it exists.
+"""
+
+import os
+import sys
+from typing import Optional
+
+
+def find_base_dir() -> str:
+    """Return the directory where this script lives (or CWD in a REPL)."""
+    return (os.path.dirname(os.path.abspath(__file__))
+            if "__file__" in globals() else os.getcwd())
+
+
+def is_hidden(name: str) -> bool:
+    """Return True if a file or directory name is considered hidden."""
+    return name.startswith(".")
+
+
+def get_jupytext() -> Optional[object]:
+    """
+    Try to import jupytext and return the module, or None if unavailable.
+
+    Prints a single warning if jupytext is not installed.
+    """
+    try:
+        import jupytext  # type: ignore
+        return jupytext
+    except ImportError:
+        print(
+            "[WARN] 'jupytext' is not installed. "
+            "Install it with 'pip install jupytext' to enable "
+            ".Rmd -> .ipynb conversion.",
+            file=sys.stderr,
+        )
+        return None
+
+
+def convert_rmd_to_ipynb(rmd_path: str, jupytext) -> None:
+    """
+    Convert a single .Rmd file to a .ipynb notebook using Jupytext.
+
+    The .ipynb file is written next to the .Rmd file. Existing notebooks
+    are overwritten.
+    """
+    base, ext = os.path.splitext(rmd_path)
+    if ext.lower() != ".rmd":
+        return
+
+    ipynb_path = base + ".ipynb"
+
+    try:
+        # Let Jupytext auto-detect the format from the extension
+        nb = jupytext.read(rmd_path)
+        jupytext.write(nb, ipynb_path)
+        print(f"Converted: {rmd_path} -> {ipynb_path}")
+    except Exception as exc:
+        print(
+            f"[ERROR] Failed to convert '{rmd_path}' to .ipynb: {exc}",
+            file=sys.stderr,
+        )
+
+
+def main() -> None:
+    base_dir = find_base_dir()
+    jupytext = get_jupytext()
+    if jupytext is None:
+        # Nothing to do if we don't have jupytext
+        return
+
+    converted_any = False
+
+    for path, folders, files in os.walk(base_dir, topdown=True):
+        # Skip hidden folders and notebook checkpoint caches
+        folders[:] = [
+            name for name in folders
+            if not is_hidden(name) and name != ".ipynb_checkpoints"
+        ]
+
+        for name in files:
+            if is_hidden(name):
+                continue
+            if not name.endswith(".Rmd"):
+                continue
+            if ".ipynb_checkpoints" in path:
+                continue
+
+            rmd = os.path.join(path, name)
+            convert_rmd_to_ipynb(rmd, jupytext)
+            converted_any = True
+
+    if not converted_any:
+        print("No .Rmd files found to convert.")
+
+
+if __name__ == "__main__":
+    main()

xarpes-0.4.0/dev_tools/Rmd2py.py → xarpes-0.5.0/dev_tools/ipynb2Rmd2py.py

@@ -15,17 +15,23 @@ Usage:
 """
 
 import os
+import re
 import shutil
 import subprocess
 import sys
 
+
 def find_base_dir() -> str:
     # Safe base directory (works both when run as script or in REPL)
-    return os.path.dirname(os.path.abspath(__file__)) if "__file__" in globals() else os.getcwd()
+    return (os.path.dirname(os.path.abspath(__file__))
+            if "__file__" in globals()
+            else os.getcwd())
+
 
 def is_hidden(name: str) -> bool:
     return name.startswith(".")
 
+
 def run_jupytext_ipynb_to_rmd(ipynb_path: str) -> bool:
     """
     Use the jupytext CLI to convert .ipynb -> .Rmd next to it.
@@ -33,29 +39,40 @@ def run_jupytext_ipynb_to_rmd(ipynb_path: str) -> bool:
     """
     jupytext = shutil.which("jupytext")
     if not jupytext:
-        print("[WARN] 'jupytext' not found on PATH. Skipping .ipynb -> .Rmd step for:",
+        print("[WARN] 'jupytext' not found on PATH. "
+              "Skipping .ipynb -> .Rmd step for:",
               ipynb_path, file=sys.stderr)
         return False
 
     cmd = [jupytext, "--to", "rmarkdown", ipynb_path]
     try:
-        res = subprocess.run(cmd, check=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+        res = subprocess.run(
+            cmd,
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
         # Optional: uncomment to see jupytext output
         # print(res.stdout, end="")
         return True
     except subprocess.CalledProcessError as e:
-        print(f"[ERROR] jupytext failed for {ipynb_path}\n{e.stdout}", file=sys.stderr)
+        print(f"[ERROR] jupytext failed for {ipynb_path}\n{e.stdout}",
+              file=sys.stderr)
         return False
 
+
 def convert_rmd_to_py(rmd_path: str) -> None:
     """
     Convert a single .Rmd file to a .py script:
     - YAML front matter is skipped
     - Markdown outside code fences is commented with '# '
-    - Code inside fences (``` or ~~~) is written verbatim (with existing magic handling)
+    - Code inside fences (``` or ~~~) is written verbatim (with existing magic
+      handling)
     """
     py_path = rmd_path[:-3] + "py"  # replace .Rmd with .py
-    with open(rmd_path, "r", encoding="utf-8") as lines, open(py_path, "w", encoding="utf-8") as text:
+    with open(rmd_path, "r", encoding="utf-8") as lines, \
+            open(py_path, "w", encoding="utf-8") as text:
         text.write("#!/usr/bin/env python3\n")
         first_magic_comment = True
         in_yaml = False
@@ -64,31 +81,33 @@ def convert_rmd_to_py(rmd_path: str) -> None:
         for raw in lines:
             line = raw
 
-            # ---- YAML front matter ------------------------------------------------
+            # ---- YAML front matter --------------------------------------------
             if line.startswith("---") and not in_code:
                 in_yaml = not in_yaml
                 continue
             if in_yaml:
                 continue
 
-            # ---- Fence open/close (```... or ~~~...) ------------------------------
+            # ---- Fence open/close (```... or ~~~...) --------------------------
             # Rmd/Quarto code chunks: ```{python, echo=FALSE} ... ```
-            if (line.lstrip().startswith("```") or line.lstrip().startswith("~~~")) and not in_yaml:
+            if (line.lstrip().startswith("```") or
+                    line.lstrip().startswith("~~~")) and not in_yaml:
                 in_code = not in_code
                 # Do not emit the fence line itself
                 continue
 
             if in_code:
-                # ---- Inside code fence: keep code, apply your filters --------------
+                # ---- Inside code fence: keep code, apply your filters ---------
                 # Skip lines marked as "Jupyter only"
                 if "Jupyter only" in line:
                     continue
 
                 # Remove IPython magics
-                if "%matplotlib widget" in line or "%matplotlib inline" in line:
+                if ("%matplotlib widget" in line or
+                        "%matplotlib inline" in line):
                     continue
 
-                # Remove global Jupyter hooks (e.g. get_ipython().events.register(...))
+                # Remove global Jupyter hooks (e.g. get_ipython().events...)
                 if "get_ipython" in line:
                     continue
 
@@ -104,22 +123,104 @@ def convert_rmd_to_py(rmd_path: str) -> None:
                 text.write(line)
 
             else:
-                # ---- Outside code fence: Markdown -> Python comments ---------------
+                # ---- Outside code fence: Markdown -> Python comments ----------
                 if line.strip() == "":
                     # Preserve blank lines (safe in Python)
                     text.write("\n")
                 else:
-                    # Comment any Markdown/text line so it doesn't break execution
+                    # Comment any Markdown/text line so it doesn't break
+                    # execution
                     text.write("# " + line)
 
+
+def normalise_rmd_metadata(rmd_path: str) -> None:
+    """
+    Standardise the YAML metadata of the Rmd file (string-based, no yaml lib):
+
+    - jupytext_version: 1.15.2
+    - kernelspec.display_name: Python 3 (ipykernel)
+    - kernelspec.name: python3
+
+    Only modifies existing lines in the YAML header. If the keys do not exist,
+    nothing is added.
+    """
+    try:
+        with open(rmd_path, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+    except OSError:
+        return
+
+    if not lines:
+        return
+
+    # Find first two '---' lines that delimit the YAML front matter.
+    if not lines[0].startswith("---"):
+        return
+
+    yaml_start = 0
+    yaml_end = None
+    for i in range(1, len(lines)):
+        if lines[i].startswith("---"):
+            yaml_end = i
+            break
+
+    if yaml_end is None:
+        # Malformed header, bail out.
+        return
+
+    header_lines = lines[yaml_start + 1:yaml_end]
+    header = "".join(header_lines)
+
+    # Replace jupytext_version
+    header = re.sub(
+        r'^(\s*jupytext_version:\s*).*$',
+        r'\g<1>1.15.2',
+        header,
+        flags=re.MULTILINE,
+    )
+
+    # Replace kernelspec.display_name
+    header = re.sub(
+        r'^(\s*display_name:\s*).*$',
+        r'\g<1>Python 3 (ipykernel)',
+        header,
+        flags=re.MULTILINE,
+    )
+
+    # Replace kernelspec.name
+    header = re.sub(
+        r'^(\s*name:\s*).*$',
+        r'\g<1>python3',
+        header,
+        flags=re.MULTILINE,
+    )
+
+    new_header_lines = header.splitlines(keepends=True)
+    new_lines = (
+        lines[:yaml_start + 1] +
+        new_header_lines +
+        lines[yaml_end:]
+    )
+
+    try:
+        with open(rmd_path, "w", encoding="utf-8") as f:
+            f.writelines(new_lines)
+    except OSError:
+        # If we can't write, silently skip; script should still continue.
+        return
+
+
 def main() -> None:
     base_dir = find_base_dir()
 
-    # ---- Pass 1: .ipynb -> .Rmd via jupytext ---------------------------------
+    # ---- Pass 1: .ipynb -> .Rmd via jupytext -------------------------------
     converted_any = False
     for path, folders, files in os.walk(base_dir, topdown=True):
         # Skip hidden folders and notebook checkpoint caches
-        folders[:] = [name for name in folders if not is_hidden(name) and name != ".ipynb_checkpoints"]
+        folders[:] = [
+            name for name in folders
+            if not is_hidden(name) and name != ".ipynb_checkpoints"
+        ]
 
         for name in files:
             if is_hidden(name):
@@ -130,14 +231,18 @@ def main() -> None:
                 continue
 
             ipynb = os.path.join(path, name)
+
+            copy_ipynb_to_docs(ipynb, base_dir)
+
             ok = run_jupytext_ipynb_to_rmd(ipynb)
             converted_any = converted_any or ok
 
     if not converted_any:
-        # Not an error—maybe there are no ipynb files, or jupytext isn't installed.
+        # Not an error—maybe there are no ipynb files, or jupytext isn't
+        # installed.
         pass
 
-    # ---- Pass 2: .Rmd -> .py (your existing logic) ---------------------------
+    # ---- Pass 2: .Rmd -> .py ----------------------------------------------
     for path, folders, files in os.walk(base_dir, topdown=True):
         folders[:] = [name for name in folders if not is_hidden(name)]
         for name in files:
@@ -147,7 +252,50 @@ def main() -> None:
                 continue
 
             rmd = os.path.join(path, name)
+
+            # Normalise jupytext/kernelspec metadata in YAML header
+            normalise_rmd_metadata(rmd)
+
+            # Convert .Rmd -> .py
             convert_rmd_to_py(rmd)
 
+
+def copy_ipynb_to_docs(ipynb_path: str, base_dir: str) -> None:
+    """
+    Copy ipynb into <repo>/doc/notebooks, flattening any subfolders.
+
+    If two notebooks share the same filename, disambiguate by appending a
+    suffix derived from their relative directory.
+    """
+    repo_root = os.path.dirname(base_dir)
+    dst_dir = os.path.join(repo_root, "doc", "notebooks")
+    os.makedirs(dst_dir, exist_ok=True)
+
+    name = os.path.basename(ipynb_path)
+    dst = os.path.join(dst_dir, name)
+
+    if os.path.exists(dst):
+        # Disambiguate collisions by using the relative folder path.
+        rel_dir = os.path.relpath(os.path.dirname(ipynb_path), base_dir)
+        rel_dir = "" if rel_dir == "." else rel_dir
+        suffix = re.sub(r"[^A-Za-z0-9]+", "_", rel_dir).strip("_")
+        root, ext = os.path.splitext(name)
+        new_name = f"{root}__{suffix}{ext}" if suffix else name
+        dst = os.path.join(dst_dir, new_name)
+
+        # If *still* colliding, add a numeric suffix.
+        if os.path.exists(dst):
+            i = 2
+            while True:
+                new_name = f"{root}__{suffix}__{i}{ext}" if suffix else \
+                           f"{root}__{i}{ext}"
+                dst = os.path.join(dst_dir, new_name)
+                if not os.path.exists(dst):
+                    break
+                i += 1
+
+    shutil.copy2(ipynb_path, dst)
+
+
 if __name__ == "__main__":
-    main()
+    main()

{xarpes-0.4.0 → xarpes-0.5.0}/doc/conf.py

@@ -24,6 +24,7 @@ extensions = [
     'sphinx.ext.viewcode',
     'numpydoc',
     'myst_parser',
+    'nbsphinx',
 ]
 
 exclude_patterns = ['README.md']
@@ -40,4 +41,4 @@ html_theme = 'sphinx_rtd_theme'
 # The following setting specifies the order in which members are documented
 autodoc_member_order = 'bysource'
 
-numpydoc_show_class_members = False
+numpydoc_show_class_members = False

xarpes-0.5.0/doc/index.rst

@@ -0,0 +1,28 @@
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+.. toctree::
+   :caption: Modules
+   :hidden:
+
+   modules/bandmap
+   modules/mdcs
+   modules/selfenergies
+   modules/distributions
+   modules/functions
+   modules/plotting
+   modules/settings_parameters
+   modules/settings_plots
+
+.. toctree::
+   :caption: Tutorials
+   :hidden:
+
+   notebooks/graphene
+   notebooks/srtio3
+
+.. toctree::
+   :caption: More
+   :hidden:
+
+   genindex

xarpes-0.5.0/doc/modules/bandmap.rst

@@ -0,0 +1,5 @@
+BandMap
+========
+
+.. automodule:: xarpes.bandmap
+   :members:

xarpes-0.5.0/doc/modules/mdcs.rst

@@ -0,0 +1,5 @@
+MDCs
+========
+
+.. automodule:: xarpes.mdcs
+   :members:

xarpes-0.5.0/doc/modules/selfenergies.rst

@@ -0,0 +1,5 @@
+SelfEnergies
+========
+
+.. automodule:: xarpes.selfenerqies
+   :members:

xarpes-0.5.0/doc/modules/settings_parameters.rst

@@ -0,0 +1,7 @@
+Settings_parameters
+===================
+
+.. automodule:: xarpes.settings_parameters
+   :members:
+   :undoc-members:
+   :show-inheritance:

xarpes-0.5.0/doc/modules/settings_plots.rst

@@ -0,0 +1,8 @@
+Settings_plots
+==============
+
+.. automodule:: xarpes.settings_plots
+   :members:
+   :private-members:
+   :undoc-members:
+   :show-inheritance: