Merge pull request #74 from easyscience/patch

Updates documentation tutorials and adds excluded regions section

Author: AndrewSazonov

.github/workflows/draft-release-notes.yml

@@ -10,45 +10,38 @@ on:
       - main
       - master
 
-  # Runs on PRs targeting the default branch (dry-run testing; does NOT update the real draft)
-  pull_request:
-    branches:
-      - main
-      - master
-
 jobs:
   draft-release-notes:
-    if: ${{ github.event_name == 'push' }}
-
     permissions:
       # write permission is required to create a github release
       contents: write
 
     runs-on: ubuntu-latest
 
     steps:
-      - name: Drafts the next Release notes
-        uses: release-drafter/release-drafter@v6
-        with:
-          disable-autolabeler: true
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Drafts the next release notes
+        uses: enhantica/drafterino@v1
 
-  # Test the Release Drafter config on PRs without modifying the real draft release
-  draft-release-notes-dry-run:
-    if: ${{ github.event_name == 'pull_request' }}
-
-    permissions:
-      contents: read
-      pull-requests: read
-
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Drafts the next Release notes (dry-run)
-        uses: release-drafter/release-drafter@v6
         with:
-          disable-autolabeler: true
-          disable-releaser: true # prevents creating/updating the draft
+          config: |
+            title: 'easydiffraction $COMPUTED_VERSION'
+            tag: 'v$COMPUTED_VERSION'
+            note-template: '- $PR_TITLE (#$PR_NUMBER)'
+
+            default-bump: post
+
+            major-bump-labels: ['[scope] significant']
+            minor-bump-labels: ['[scope] enhancement']
+            patch-bump-labels: ['[scope] bug', '[scope] maintenance']
+            post-bump-labels: ['[scope] documentation']
+
+            release-notes:
+              - title: 'Added'
+                labels: ['[scope] significant', '[scope] enhancement']
+              - title: 'Fixed'
+                labels: ['[scope] bug']
+              - title: 'Changed'
+                labels: ['[scope] maintenance', '[scope] documentation']
+
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test-code.yaml

@@ -197,6 +197,19 @@ jobs:
           export PYTHONPATH="$(pwd)/src${PYTHONPATH:+:$PYTHONPATH}"
           python -m pytest tests/functional_tests/ --color=yes -n auto
 
+      # Ensures a consistent high version like 999.0.0 when not on a tagged commit
+      # This is needed for testing the package in the next job, as its version
+      # must be higher than the PyPI version for pip to prefer the local version.
+      - name: Inject fallback version tag if not on a real tag
+        shell: bash
+        run: |
+          if ! git describe --tags --match "v*" --exact-match > /dev/null 2>&1; then
+            echo "Not on release tag — applying fallback 'v999.0.0'"
+            git tag v999.0.0
+          else
+            echo "On a valid tag"
+          fi
+
       - name: Create Python package for the next job
         shell: bash
         run: python -m build --wheel --outdir dist

docs/user-guide/analysis-workflow/experiment.md

@@ -132,15 +132,23 @@ which makes it easier to manage the experiment:
    depends on the experiment type, but generally includes columns for 2θ angle
    or TOF and intensity.
 
-### 1. Instrument Category
+### 1. Instrument Category { #instrument-category }
 
 ```python
 # Modify the default instrument parameters
 project.experiments['hrpt'].instrument.setup_wavelength = 1.494
 project.experiments['hrpt'].instrument.calib_twotheta_offset = 0.6
 ```
 
-### 2. Peak Category
+### 2. Excluded Regions Category { #excluded-regions-category }
+
+```python
+# Add excluded regions to the experiment
+project.experiments['hrpt'].excluded_regions.add(start=0, end=10)
+project.experiments['hrpt'].excluded_regions.add(start=160, end=180)
+```
+
+### 3. Peak Category { #peak-category }
 
 ```python
 # Select the desired peak profile type
@@ -154,7 +162,7 @@ project.experiments['hrpt'].peak.broad_lorentz_x = 0
 project.experiments['hrpt'].peak.broad_lorentz_y = 0.1
 ```
 
-### 3. Background Category
+### 4. Background Category { #background-category }
 
 ```python
 # Select the desired background type
@@ -168,14 +176,14 @@ project.experiments['hrpt'].background.add(x=110, y=170)
 project.experiments['hrpt'].background.add(x=165, y=170)
 ```
 
-### 4. Linked Phases Category
+### 5. Linked Phases Category { #linked-phases-category }
 
 ```python
 # Link the sample model defined in the previous step to the experiment
 project.experiments['hrpt'].linked_phases.add(id='lbco', scale=10.0)
 ```
 
-### 5. Measured Data Category
+### 6. Measured Data Category { #measured-data-category }
 
 If you do not have a CIF file for your experiment, you can load measured data
 from a file in a supported format. The measured data will be automatically

docs/user-guide/analysis-workflow/model.md

@@ -79,21 +79,21 @@ to manage the model:
 3. **Atom Sites Category**: Describes the positions and properties of atoms
    within the unit cell.
 
-### 1. Space Group Category
+### 1. Space Group Category { #space-group-category }
 
 ```python
 # Set space group
 project.sample_models['nacl'].space_group.name_h_m = 'F m -3 m'
 ```
 
-### 2. Cell Category
+### 2. Cell Category { #cell-category }
 
 ```python
 # Define unit cell parameters
 project.sample_models['nacl'].cell.length_a = 5.691694
 ```
 
-### 3. Atom Sites Category
+### 3. Atom Sites Category { #atom-sites-category }
 
 ```python
 # Add atomic sites

docs/user-guide/first-steps.md

@@ -87,8 +87,11 @@ example datasets without having to manually download them.
 
 EasyDiffraction provides several helper methods to display supported engines for
 calculation, minimization, and plotting. These methods can be called on the
-`Project` instance to display the available options for each category. For
-example, you can use the `show_supported_calculators()` method to see which
+`Project` instance to display the available options for different categories.
+
+### Supported calculators
+
+For example, you can use the `show_supported_calculators()` method to see which
 calculation engines are available for use in your project:
 
 ```python
@@ -105,8 +108,19 @@ An example of the output for the `show_supported_calculators()` method is:
 | cryspy     | CrysPy library for crystallographic calculations            |
 | pdffit     | PDFfit2 library for pair distribution function calculations |
 
-Other helper methods include those for showing the available parameters grouped
-in different categories. For example, you can use:
+### Supported minimizers
+
+You can also check the available minimizers using the
+`show_available_minimizers()` method:
+
+```python
+project.show_available_minimizers()
+```
+
+### Available parameters
+
+EasyDiffraction provides several methods for showing the available parameters
+grouped in different categories. For example, you can use:
 
 - `project.analysis.show_all_params()` – to display all available parameters for
   the analysis step.
@@ -135,6 +149,22 @@ method is:
 | 60  | project.experiments['hrpt'].peak.broad_gauss_v         | hrpt.peak.broad_gauss_v          |
 | 61  | project.experiments['hrpt'].peak.broad_gauss_w         | hrpt.peak.broad_gauss_w          |
 
+### Supported plotters
+
+To see the available plotters, you can use the `show_available_plotters()`
+method on the `plotter` attribute of the `Project` instance:
+
+```python
+project.plotter.show_supported_engines()
+```
+
+An example of the output is:
+
+| Engine       | Description                                |
+| ------------ | ------------------------------------------ |
+| asciichartpy | Console ASCII line charts                  |
+| plotly       | Interactive browser-based graphing library |
+
 ## Data analysis workflow
 
 Once the EasyDiffraction package is imported, you can proceed with the **data

pyproject.toml

@@ -16,9 +16,9 @@ classifiers = [
   'Operating System :: OS Independent',
   'Programming Language :: Python :: 3 :: Only',
   'Programming Language :: Python :: 3',
-  "Programming Language :: Python :: 3.11",
-  "Programming Language :: Python :: 3.12",
-  "Programming Language :: Python :: 3.13",
+  'Programming Language :: Python :: 3.11',
+  'Programming Language :: Python :: 3.12',
+  'Programming Language :: Python :: 3.13',
 ]
 requires-python = '>=3.11,<3.14'
 dependencies = [
@@ -117,6 +117,9 @@ distance = '{base_version}.post{distance}'       # example: 1.2.3.post42
 dirty = '{base_version}'                         # example: 1.2.3
 distance-dirty = '{base_version}.post{distance}' # example: 1.2.3.post42
 
+# Configure how versioningit detects versions from Git
+# - 'match' ensures it only considers tags starting with 'v'
+# - 'default-tag' is used as a fallback when no matching tag is found
 [tool.versioningit.vcs]
 method = 'git'
 match = ['v*']

src/easydiffraction/analysis/calculators/calculator_crysfml.py

@@ -20,7 +20,8 @@
 
     print("✅ 'pycrysfml' calculation engine is successfully imported.")
 except ImportError:
-    print("⚠️ 'pycrysfml' module not found. This calculation engine will not be available.")
+    # TODO: Add the following print to debug mode
+    # print("⚠️ 'pycrysfml' module not found. This calculation engine will not be available.")
     cfml_py_utilities = None
 
 

src/easydiffraction/analysis/calculators/calculator_cryspy.py

@@ -23,7 +23,8 @@
 
     print("✅ 'cryspy' calculation engine is successfully imported.")
 except ImportError:
-    print("⚠️ 'cryspy' module not found. This calculation engine will not be available.")
+    # TODO: Add the following print to debug mode
+    # print("⚠️ 'cryspy' module not found. This calculation engine will not be available.")
     cryspy = None
 
 

src/easydiffraction/analysis/calculators/calculator_pdffit.py

@@ -19,7 +19,8 @@
     redirect_stdout(open(os.path.devnull, 'w'))  # silence the C++ engine output
     print("✅ 'pdffit' calculation engine is successfully imported.")
 except ImportError:
-    print("⚠️ 'pdffit' module not found. This calculation engine will not be available.")
+    # TODO: Add the following print to debug mode
+    # print("⚠️ 'pdffit' module not found. This calculation engine will not be available.")
     pdffit = None
 
 

src/easydiffraction/analysis/minimizers/minimizer_factory.py

@@ -55,6 +55,9 @@ def list_available_minimizers(cls) -> List[str]:
 
     @classmethod
     def show_available_minimizers(cls) -> None:
+        # TODO: Rename this method to `show_supported_minimizers` for
+        #  consistency with other methods in the library. E.g.
+        #  `show_supported_calculators`, etc.
         """
         Display a table of available minimizers and their descriptions.
         """