From db2844f04d1dd5f7ed4e0a7bc856c16911b57dd3 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Mon, 4 May 2026 10:31:14 -0400 Subject: [PATCH 01/23] docs: added github link and source code links to github pages --- docs/conf.py | 10 ++++++++++ index.md | 18 ------------------ 2 files changed, 10 insertions(+), 18 deletions(-) delete mode 100644 index.md diff --git a/docs/conf.py b/docs/conf.py index 7deea7df..4a2adfe9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,6 +22,7 @@ extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', 'sphinx.ext.doctest', 'sphinx.ext.githubpages', 'sphinx.ext.intersphinx', @@ -93,5 +94,14 @@ ], } +# Add Github repo link for `sphinx_rtd_theme` theme +html_context = { + 'display_github': True, # Integrate GitHub +# 'github_user': 'MyUserName', # Your username +# 'github_repo': 'MyRepoName', # Your repo name + 'github_version': 'main', # The branch name + 'conf_py_path': '/docs/', # Path in the checkout to the docs root +} + # If true, links to the reST sources are added to the pages. html_show_sourcelink = False diff --git a/index.md b/index.md deleted file mode 100644 index 9ecb870b..00000000 --- a/index.md +++ /dev/null @@ -1,18 +0,0 @@ -### CHAP installation -- [Installation](docs/installation.md) - -### Workflow introductions -- [Energy Dispersive Diffraction (EDD)](docs/workflows/EDD.md) -- [Tomography](docs/workflows/Tomo.md) - - From f5f950cb9d73621a99bdc68d5f9f6c5c39e6b852 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Mon, 4 May 2026 11:15:44 -0400 Subject: [PATCH 02/23] docs: fix added github link to new sphinx autodoc version --- docs/_templates/breadcrumbs.html | 8 ++++++++ docs/_templates/layout.html | 14 ++++++++++++++ docs/conf.py | 8 +++----- 3 files changed, 25 insertions(+), 5 deletions(-) create mode 100644 docs/_templates/breadcrumbs.html create mode 100644 docs/_templates/layout.html diff --git a/docs/_templates/breadcrumbs.html b/docs/_templates/breadcrumbs.html new file mode 100644 index 00000000..9c21555f --- /dev/null +++ b/docs/_templates/breadcrumbs.html @@ -0,0 +1,8 @@ +{% extends "!breadcrumbs.html" %} + +{% block breadcrumbs_aside %} +
  • + GitHub +
    • +{% endblock %} + diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 00000000..8f6767eb --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,14 @@ +{% extends "!layout.html" %} + +{% block menu %} + {{ super() }} +

    External Links

    + +{% endblock %} + diff --git a/docs/conf.py b/docs/conf.py index 4a2adfe9..fc5555b0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -95,12 +95,10 @@ } # Add Github repo link for `sphinx_rtd_theme` theme +# See also _templates/breadcrumbs.html and _templates/layout.html +templates_path = ['_templates'] html_context = { - 'display_github': True, # Integrate GitHub -# 'github_user': 'MyUserName', # Your username -# 'github_repo': 'MyRepoName', # Your repo name - 'github_version': 'main', # The branch name - 'conf_py_path': '/docs/', # Path in the checkout to the docs root + 'display_github': True, } # If true, links to the reST sources are added to the pages. From b6076c1a33fd113b363663c78d0c2f63e447a31e Mon Sep 17 00:00:00 2001 From: Rolf Verberg <59030403+rolfverberg@users.noreply.github.com> Date: Mon, 4 May 2026 13:58:36 -0400 Subject: [PATCH 03/23] Update EDD.md Add a spec.log instead of par file map example --- docs/workflows/EDD.md | 63 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/docs/workflows/EDD.md b/docs/workflows/EDD.md index 688e85f9..579025ec 100644 --- a/docs/workflows/EDD.md +++ b/docs/workflows/EDD.md @@ -254,6 +254,69 @@ The remainder of the file contains the actual workflow pipeline, in this example Note that the energy calibration can also be obtained ahead of time and used for multiple strain analyses. In this case remove the first two blocks in the pipeline and read the detector channel energy/$2\theta$ calibration info in what is now the third block in the pipeline, labelled `map`. +### Creating the CHESS stype strain analysis map without a par-file + +The above strain analysis workflow example can also be executed without availablity of a CHESS style experiment par-file, by reading the raw data information directly from the SPEC log file. In this case the map construction part description of the workflow in the `pipeline.yaml` file must be replaced by the following: +```yaml +map: + + # Create a CHESS style map + - common.MapProcessor: + config: + title: # Enter an appropriate name (like the BTR) + station: id1a3 + experiment_type: EDD + sample: + name: # Enter the sample name + description: '' + spec_scans: # Edit both SPEC log file path and EDD scan numbers + # Path can be relative to inputdir or absolute + - spec_file: /spec.log + scan_numbers: 1-4 + scalar_data: # Add or modify as appropriate + - label: SCAN_N + units: n/a + data_type: smb_par + name: SCAN_N # Change as needed + independent_dimensions: + # Add or modify as appropriate + - label: labx + units: mm + data_type: smb_par + name: labx # Change as needed + - label: laby + units: mm + data_type: smb_par + name: laby # Change as needed + - label: labz + units: mm + data_type: smb_par + name: labz # Change as needed + presample_intensity: + label: presample_intensity + units: counts + data_type: scan_column + name: a3ic1 # Change as needed + dwell_time_actual: + label: dwell_time_actual + units: s + data_type: scan_column + name: sec # Change as needed + postsample_intensity: + label: postsample_intensity + units: counts + data_type: scan_column + name: diode # Change as needed + detector_config: + detectors: # Use available detector elements when omitted + - id: 0 + - id: 11 + - id: 22 + - common.NexusWriter: + filename: map.nxs # NeXus map output filename + force_overwrite: true +``` + ## Additional notes on energy calibration As mentioned above a standard EDD experiment needs calibration of the detector channel energies. Experiments have shown that the channel energies $E_j$ vary linearly with the channel index $j$ within the energy range of typical EDD experiments: $E_j = mj+b$, where the slope $m$ and intercept $b$ can be determined in one or a combination of two experiments: From fd324648baf92fe84d664bd449d3463f1a205477 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Tue, 5 May 2026 18:51:24 -0400 Subject: [PATCH 04/23] add: Added details to documentation on EDD detector configuration Also fixed and made CHAP.edd.model.FitConfig public again, so that it shows up in the reference guide. --- CHAP/edd/models.py | 14 ++++---- CHAP/edd/processor.py | 4 +-- docs/_templates/layout.html | 2 +- docs/workflows/EDD.md | 65 ++++++++++++++++++++++++++++++++++++- 4 files changed, 74 insertions(+), 11 deletions(-) diff --git a/CHAP/edd/models.py b/CHAP/edd/models.py index d224a69e..e2a9cad7 100755 --- a/CHAP/edd/models.py +++ b/CHAP/edd/models.py @@ -64,7 +64,7 @@ class BaselineConfig(CHAPBaseModel): # Fit configuration class -class _FitConfig(CHAPBaseModel): +class FitConfig(CHAPBaseModel): """Fit parameters configuration class for peak fitting. :ivar background: Background model for peak fitting, defaults @@ -237,9 +237,9 @@ def validate_materialconfig_after(self): # Avoid Pydantic "Class not fully defined" in sphinx autodoc as a # result of lazy importing by using in an _exclude pydantic instance # variable -_FitConfig.model_rebuild(_types_namespace=vars(typing)) +FitConfig.model_rebuild(_types_namespace=vars(typing)) -class MCADetectorCalibration(Detector, _FitConfig): +class MCADetectorCalibration(Detector, FitConfig): """Class representing the configuration for a single MCA detector element to perform detector calibration. @@ -547,7 +547,7 @@ def get_tth_map(self, map_shape): ] -class MCADetectorConfig(_FitConfig): +class MCADetectorConfig(FitConfig): """Class representing metadata required to configure a full MCA detector. @@ -559,7 +559,7 @@ class MCADetectorConfig(_FitConfig): 'calibration', 'diffractionvolumelength', 'strainanalysis'] detectors: Optional[conlist(min_length=1, item_type=MCADetector)] = [] - _exclude = set(vars(_FitConfig()).keys()) + _exclude = set(vars(FitConfig()).keys()) @model_validator(mode='before') @classmethod @@ -611,7 +611,7 @@ def update_detectors(self): # Processor configuration classes -class DiffractionVolumeLengthConfig(_FitConfig): +class DiffractionVolumeLengthConfig(FitConfig): """Configuration for the differential volume length processor :class:`~CHAP.edd.processor.DiffractionVolumeLengthProcessor` for an EDD setup using a steel-foil raster scan. @@ -639,7 +639,7 @@ class DiffractionVolumeLengthConfig(_FitConfig): sample_thickness: Optional[confloat(gt=0, allow_inf_nan=False)] = None sigma_to_dvl_factor: Optional[Literal[2.0, 3.5, 4.0]] = 3.5 - _exclude = set(vars(_FitConfig()).keys()) + _exclude = set(vars(FitConfig()).keys()) @model_validator(mode='after') def validate_diffractionvolumelengthconfig_after(self): diff --git a/CHAP/edd/processor.py b/CHAP/edd/processor.py index 2309ff78..5d67fc3c 100755 --- a/CHAP/edd/processor.py +++ b/CHAP/edd/processor.py @@ -1015,7 +1015,7 @@ def process(self, data): if len(sskipped_detectors) == 1: self.logger.warning( f'Skipping detector {sskipped_detectors[0]} ' - '(no raw data)') + '(no calibration data)') elif sskipped_detectors: skipped_detectors = [int(d) for d in sskipped_detectors] self.logger.warning( @@ -2747,7 +2747,7 @@ def process(self, data): if len(sskipped_detectors) == 1: self.logger.warning( f'Skipping detector {sskipped_detectors[0]} ' - '(no raw data)') + '(no calibration data)') elif sskipped_detectors: skipped_detectors = [int(d) for d in sskipped_detectors] self.logger.warning( diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index 8f6767eb..4933b90d 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -5,7 +5,7 @@

    External Links

    • - + GitHub Repository
      • diff --git a/docs/workflows/EDD.md b/docs/workflows/EDD.md index 579025ec..290d679c 100644 --- a/docs/workflows/EDD.md +++ b/docs/workflows/EDD.md @@ -224,7 +224,7 @@ The "config" block defines the CHAP generic configuration parameters: - `log_level`: The [Python logging level](https://docs.python.org/3/library/logging.html#levels). -The remainder of the file contains the actual workflow pipeline, in this example it consists of four blocks, `energy`, `tththeta`, `map`, and `strain`, which can be executed individually or all at once [as described here](chap_pipeline). In addition to the readers and writers of the intermediate results, nine toplevel processes get executed successively in the combined four pipeline blocks: +The remainder of the file contains the actual workflow pipeline, in this example it consists of four blocks, `energy`, `twotheta`, `map`, and `strain`, which can be executed individually or all at once [as described here](chap_pipeline). In addition to the readers and writers of the intermediate results, nine toplevel processes get executed successively in the combined four pipeline blocks: - The EDD/XRF energy calibration consists of two processes: @@ -317,6 +317,69 @@ map: force_overwrite: true ``` +### Specifying the detector configuration in the EDD workflow + +#### Selecting detectors for detector calibration + +In the example above, the raw data for both the energy and the $2\theta$ calibration is read by the `common.SpecReader` pipeline item, while which detectors to include in the calibration is specified in the `detectors` field under `detector_config` in the `edd.MCAEnergyCalibrationProcessor` and `edd.MCATthCalibrationProcessor` pipeline items, respectively. +However, this is not the only way to specify the detectors to use. As can be seen from the documentation for [`SpecReader`](https://chesscomputing.github.io/ChessAnalysisPipeline/CHAP.common.html#CHAP.common.reader.SpecReader), the detectors for which raw data is read can also be specified by adding a `detector_config` field to the `SpecReader`. For example, by using the following in the pipeline file for the EDD workflow above: +```yaml + - common.SpecReader: + config: + station: id1a3 # Change as needed + experiment_type: EDD + spec_scans: # Edit both SPEC log file path and EDD scan numbers + # Path can be relative to inputdir (line 3) or absolute + - spec_file: /spec.log + scan_numbers: 1 + detector_config: + detectors: # Choose the detectors + # Use all available detector elements when omitted + - id: 0 + - id: 11 + - id: 22 +``` +When the `detector_config` or `detectors` field is omitted in the `MCAEnergyCalibrationProcessor` configuration, the energy calibration will be performed for all detectors for which raw data is read. With the `detectors` field specified, the energy calibration is performed for only *those detectors* that are selected there that are *also* read by `SpecReader`. Any detector selected in the `MCAEnergyCalibrationProcessor` configuration that is not read by `SpecReader` will be *omitted* (resulting in a "no raw data" warning). +The same detector selection mechanism is valid for $2\theta$ calibration, with the added feature that any detector selected during the energy calibration will be included automatically during $2\theta$ calibration, *irrespective* of it being selected in the `MCATthCalibrationProcessor` configuration (contingent upon the reading of the appropriate raw data by the preceeding `SpecReader`). + +#### Selecting detectors for Strain analysis + +A similar detector selection approach is available for the strain analysis among the `MapProcessor` and the `StrainAnalysisProcessor` configurations and the availablity of calibrated detector data. When the `detector_config` or `detectors` field is omitted in the `StrainAnalysisProcessor` configuration, the strain analysis will be performed for all detectors for which both raw data is read by `MapProcessor` and for which calibrated detector data is read by the `common.YAMLReader` pipeline item under the `strain` block in the pipeline file above. With the `detectors` field specified, the detectors that are used are further restricted to only those that are listed in its field under the `edd.StrainAnalysisProcessor` pipeline item. Any detector selected in the `StrainAnalysisProcessor` configuration for which raw data from `MapProcessor` is missing is skipped accompanied by a "no raw data" warning. Similarly, any selected detector for which detector calibration input is missing is skipped accompanied by a "no calibration data" warning. + +#### Selecting other parameters in the detector configuration + +In addition to which detectors to include, the user also has the choice to pick many other parameters that affect the detector configuration and the EDD workflow. Some are specific to certain processors in the EDD workflow, but a certain set, those in the [`FitConfig`](https://chesscomputing.github.io/ChessAnalysisPipeline/CHAP.edd.html#CHAP.edd.model.FitConfig) configuration class, can be specified both on a *per-detector-basis* as well as on a *for-all-detectors basis*. This is evident from the fact that both [`MCADetectorConfig`](https://chesscomputing.github.io/ChessAnalysisPipeline/CHAP.edd.html#CHAP.edd.model.MCADetectorConfig) as well the list entries in its `detectors` field are derived from `FitConfig`. The generic behavior for each of these parameters is that those specified on the *for-all-detector* level, i.e. as items of the `detector_config` fields, superseed those that are specified on a *per-detector-basis*. + +Take for example two scenarios for the detector configuration in the energy calibration step: + +- as specified in the pipeline file above: + ```yaml + detector_config: + baseline: true + mask_ranges: [[650, 850]] + detectors: + - id: 0 + - id: 11 + - id: 22 + ``` + +- or specified as follows: + ```yaml + detector_config: + mask_ranges: [[650, 850]] + detectors: + - id: 0 + baseline: true + - id: 11 + mask_ranges: [[600, 850]] + - id: 22 + baseline: + lam: 1.e-5 + mask_ranges: [[650, 900]] + ``` + +The first case will set `baseline` and `mask_range` for each detector to the *same* value specified by the respective values in the `detector_config` configuration. The same happens for `mask_range` in the second case, where its entries for detector 11 and 22 are ignored. Whereas, the `baseline` parameter for detector 0, 11 and 22 is set to `True`, `False` (its default value), and `True` with a smoothness parameter, lam, of $10^{-5}$, respectively. + ## Additional notes on energy calibration As mentioned above a standard EDD experiment needs calibration of the detector channel energies. Experiments have shown that the channel energies $E_j$ vary linearly with the channel index $j$ within the energy range of typical EDD experiments: $E_j = mj+b$, where the slope $m$ and intercept $b$ can be determined in one or a combination of two experiments: From 38822cc0b5a6c71719b5dd10d5236331b9bb79de Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Tue, 5 May 2026 19:26:11 -0400 Subject: [PATCH 05/23] docs: added a link to github issues on the github pages --- docs/_templates/layout.html | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index 4933b90d..1dec2699 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -8,6 +8,9 @@ GitHub Repository + + Open or contribute to GitHub issues +
    {% endblock %} From e2ba909d0da3f09cbabef33160b3c103b3e3590c Mon Sep 17 00:00:00 2001 From: Rolf Verberg <59030403+rolfverberg@users.noreply.github.com> Date: Tue, 5 May 2026 20:19:47 -0400 Subject: [PATCH 06/23] Update README.md --- README.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e0365822..04c675ec 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,23 @@ ![unittests](https://github.com/CHESSComputing/ChessAnalysisPipeline/actions/workflows/unittests.yml/badge.svg) # ChessAnalysisPipeline (CHAP) -CHAP is a package that provides a framework for executing data anlaysis pipelines. The package can be found on PyPI and conda-forge. -## Subpackages -There are several subpackages within CHAP that contain specialized items to handle specific types of data processing in the CHAP framework. Dependencies for these subpackages can be found in `CHAP//environment.yml`. +## :bulb: About +The CHESS Analysis Pipeline (CHAP) package is an object-oriented python framework for executing data reduction and analysis workflows by refactoring workflows into modular pipelines composed of interchangeable, reusable code components where each basic pipeline block consists of a reader, processor, and/or writer. Please check the CHAP [introduction](https://chesscomputing.github.io/ChessAnalysisPipeline/introduction.html) for a broad outline of its basic framework. -## Documentation -Documentation for the latest version can be found on [this project's github pages site](https://chesscomputing.github.io/ChessAnalysisPipeline/). +## :hammer_and_wrench: Installation +The package is available over PyPI and conda-forge. See the [installation instructions](https://chesscomputing.github.io/ChessAnalysisPipeline/installation.html) for installing CHAP on any Linux system. + +#### :package: Subpackages +There are several subpackages within CHAP that contain specialized items to handle specific types of data processing workflows in the CHAP framework. Dependencies for these subpackages can be found in `CHAP//environment.yml`. Details on how to install a conda environment for each of these subpackages are also included in the [installation instructions](https://chesscomputing.github.io/ChessAnalysisPipeline/installation.html) + +## :books: Documentation +Documentation for the latest release version can be found on [this project's github pages site](https://chesscomputing.github.io/ChessAnalysisPipeline/). + +## :handshake: Contributing +We welcome feedback, suggestions, issues and bug reports. + +Feel free to contribute by [submitting an issue](https://chesscomputing.github.io/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. +When submitting an issue, please have a look at the [contribution guidelines](https://chesscomputing.github.io/ChessAnalysisPipeline/contributions.html). Following these guidelines grately helps us to address each issue promptly and effectively. + +We appreciate your support! From 42475261504f1ebd254a59a26947621fd737f432 Mon Sep 17 00:00:00 2001 From: Keara Soloway Date: Fri, 5 Jun 2026 12:27:09 -0400 Subject: [PATCH 07/23] doc: add recommended XPS23 detector config confirmed with measurement --- docs/workflows/EDD.md | 72 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/docs/workflows/EDD.md b/docs/workflows/EDD.md index 290d679c..55d7636d 100644 --- a/docs/workflows/EDD.md +++ b/docs/workflows/EDD.md @@ -380,6 +380,78 @@ Take for example two scenarios for the detector configuration in the energy cali The first case will set `baseline` and `mask_range` for each detector to the *same* value specified by the respective values in the `detector_config` configuration. The same happens for `mask_range` in the second case, where its entries for detector 11 and 22 are ignored. Whereas, the `baseline` parameter for detector 0, 11 and 22 is set to `True`, `False` (its default value), and `True` with a smoothness parameter, lam, of $10^{-5}$, respectively. +#### Recommended XPS23 detector configuration +Below is good configuration for the CHESS XPS23 detector. Use it as a starting point for the XPS23 configuration in your workflow. It can be used either as a `detector_config` parameter directly in your `pipeline.yaml` file and/or as the contents of a separate `detector_config.yaml` file that can be read into the data in your pipeline with a `YAMLReader` and `schema: common.models.map.DetectorConfig`): +```yaml +detectors: +- id: 0 + attrs: + eta: -180.0 +- id: 1 + attrs: + eta: -171.8181818181818 +- id: 2 + attrs: + eta: -163.63636363636363 +- id: 3 + attrs: + eta: -155.45454545454544 +- id: 4 + attrs: + eta: -147.27272727272728 +- id: 5 + attrs: + eta: -139.0909090909091 +- id: 6 + attrs: + eta: -130.9090909090909 +- id: 7 + attrs: + eta: -122.72727272727272 +- id: 8 + attrs: + eta: -114.54545454545455 +- id: 9 + attrs: + eta: -106.36363636363636 +- id: 11 + attrs: + eta: -98.18181818181819 +- id: 10 + attrs: + eta: -90.0 +- id: 12 + attrs: + eta: -81.81818181818181 +- id: 13 + attrs: + eta: -73.63636363636364 +- id: 14 + attrs: + eta: -65.45454545454545 +- id: 15 + attrs: + eta: -57.27272727272728 +- id: 16 + attrs: + eta: -49.09090909090909 +- id: 17 + attrs: + eta: -40.90909090909091 +- id: 18 + attrs: + eta: -32.72727272727272 +- id: 19 + attrs: + eta: -24.54545454545456 +- id: 21 + attrs: + eta: -8.181818181818187 +- id: 22 + attrs: + eta: 0.0 +``` + ## Additional notes on energy calibration As mentioned above a standard EDD experiment needs calibration of the detector channel energies. Experiments have shown that the channel energies $E_j$ vary linearly with the channel index $j$ within the energy range of typical EDD experiments: $E_j = mj+b$, where the slope $m$ and intercept $b$ can be determined in one or a combination of two experiments: From f88e147c3259c4ea69552c403073bc6b91a90129 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 10 Jun 2026 14:54:04 -0400 Subject: [PATCH 08/23] doc: added AUTHORS and docs/CONTRIBUTIONS.md --- AUTHORS | 8 ++ LICENSE | 2 +- README.md | 2 +- docs/CONTRIBUTIONS.md | 236 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 6 ++ docs/workflows/EDD.md | 2 +- 6 files changed, 253 insertions(+), 3 deletions(-) create mode 100644 AUTHORS create mode 100644 docs/CONTRIBUTIONS.md diff --git a/AUTHORS b/AUTHORS new file mode 100644 index 00000000..5b59353e --- /dev/null +++ b/AUTHORS @@ -0,0 +1,8 @@ +AUTHORS + +# The official list of Cornell High Energy Synchrotron Source (CHESS) authors of the CHESSComputing organization for copyright purposes + +- Valentin Kuznetsov, Cornell University +- Keara L Soloway, Cornell University +- Werner Sun, Cornell University +- Rolf Verberg, Cornell University diff --git a/LICENSE b/LICENSE index d0b1e9b5..4775e04e 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 Valentin Kuznetsov +Copyright (c) 2023 The ChessAnalysisPipeline (CHAP) Authors (see AUTHORS file) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 04c675ec..43434bde 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Documentation for the latest release version can be found on [this project's git ## :handshake: Contributing We welcome feedback, suggestions, issues and bug reports. -Feel free to contribute by [submitting an issue](https://chesscomputing.github.io/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. +Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. When submitting an issue, please have a look at the [contribution guidelines](https://chesscomputing.github.io/ChessAnalysisPipeline/contributions.html). Following these guidelines grately helps us to address each issue promptly and effectively. We appreciate your support! diff --git a/docs/CONTRIBUTIONS.md b/docs/CONTRIBUTIONS.md new file mode 100644 index 00000000..01786f03 --- /dev/null +++ b/docs/CONTRIBUTIONS.md @@ -0,0 +1,236 @@ +(contributions)= +# Contributions + +RV CONTRIBUTING.md should be in your root directory + +We welcome feedback, suggestions, issues and bug reports. + +Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. + +We appreciate your support! + +## How to contribute + +CHAP is an open source project and we encourage and gratefully receive feedback or contributions to improve our product. Please follow these guidelines to contribute to CHAP. Doing so grately helps us to address each contribution promptly and effectively. + +There are many ways to contribute, from supplying examples, improving the documentation, submitting bug reports and feature requests or writing code that can be incorporated into CHAP itself. +Please [submit an issue](submit_chap_issue) to report a bug or request new features. Actual bug fixes or other types of contributions to the source code or documentation should be submitted after [creating a fork](create_chap_fork) and making a [pull request](make_chap_pull_request). Please do not use the issue tracker for support questions or to leave feedback. Instead, feel free to contact any of the administators directly. + +Please only report a bug or request a new feature after checking the [existing open issues](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) and verifying that it has not yet been reported, requested or addressed! + +(submit_chap_issue)= +### Submitting an issue + +If you find a security vulnerability, do NOT open an issue. Contact any of the administators instead. + +#### Reporting a bug + +Report a bug by following these step to submit an issue: + +1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. + +1. Select the "CHAP CLI Bug report" option to open a template to provide us with information to help us track and reproduce the error. + +1. After the "CHAP CLI Bug report" interface opens: + + a. Supply a clear and concise title to identify the issue. + + b. Edit and fill out the description form, being as specific as you can in answering each of the following items: + + - Give a clear and concise description of the nature of the bug. + + - Provide a minimal pipeline configuration in which the bug appears. + + - Describe what you expected to happen. + + - Describe what actually happens and if possible add a record or a screen shot of the (relevant part of the) CHAP logger output to show the error or explain the problem. + + - Provide information of the OS, CHAP version and python/conda environment. + + - Provide any additional information that can help in tracking down the issue. + + c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. + +#### Suggesting or requesting a new feature or enhancement + +Request a new feature by following these step to submit an issue: + +1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. + +1. Select the "New PipelineItem request" option to open a template to provide us with information that helps us to modify existing or create new CHAP `PipelineItem`s to implement the feature. + +1. After the "New PipelineItem request" dialogue interface opens: + + a. Supply a clear and concise title to describe the feature. + + b. Edit and fill out the description form, being as specific as you can in answering each of the following items: + + - Describe the intended use of the requested feature. + + - Describe the feature's inputs. + + - Describe the feature's optional interaction points. + + - Describe the feature's output. + + - Provide any additional information that can help in implementing the new feature. + + c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. + +#### Reporting any other issue + +Follow these these step to submit any other issue, not covered by either option above: + +1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. + +1. Select the "Blank issue" option to open a template to provide us with information to help us resolve the issue. + +1. After the new issue interface opens: + + a. Supply a clear and concise title to identify the issue, + + b. Edit and fill out the description form, being as specific as you can. + + c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. + +Check out the [Github documentation](https://docs.github.com/en) on [creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue) for additional helpful hints. + +### Directly contributing to the source code or documentation + +Actual bug fixes or other types of contributions to the source code or documentation should be submitted by making a pull request from your own fork. +Whether you are fixing bugs, adding features, or improving documentation, following the steps below ensures that any contributions can be verified and vetted by the administrators before incorporation into the main code base. To contribute directly to CHAP, you will need your own account on [Github](https://github.com). + +(create_chap_fork)= +#### Create your own fork + +Start by creating your own copy or "fork" of the CHAP repository before starting to contribute directly to the source code or documentation. This creates a copy of the repository that shares the code and documentation with the original CHAP repository, but that lets you make modifications or additions without directly affecting the source. + +Create a fork by following these steps: + +1. In a web browser, navigate to the [CHAP repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub. + +1. In the top-right corner of the page, click "Fork". + +1. After the "Create a new fork" interface opens: + + a. Select your own personal Github account under "Choose an owner". By default, forks are named the same as their upstream repositories. To follow this convention, leave the Repository name unchanged as "ChessAnalysisPipeline". + + b. Optionally, in the "Description" field, type a description of your fork. + + c. It is strongly recommended to select "Copy the main branch only" (its default setting). + + d. Click on the green "Create fork" button. + +#### Clone your fork to your computer + +After creating your own CHAP fork, you also need to create a local copy of the project or "clone" on your own computer. To clone your forked repositiory: + +1. Click on the green "<> Code" botton. + +1. Copy the URL for the repository: Under the "Local" tab choose to clone the repository using HTTPS or using an SSH key by selecting the respective tab and clicking the "Copy URL to clipboard" button to the right of the corresponding link. Choose HTTPS for a fast and easy setup if you just want to inspect the code base. Choose SSH if you plan to contribute frequently and want to avoid needing to enter your credentials for every push or pull. + +1. On Mac or Linux, open a Terminal. On Windows, open Git Bash. + +1. Change to the location where you want the cloned directory. + +1. Type git clone, and then paste the URL you copied earlier. It should look like: + ```bash + $ git clone https://github.com//ChessAnalysisPipeline.git + ``` + or + ```bash + $ git clone git@github.com:/ChessAnalysisPipeline.git + ``` + for cloning with HTTPS or SSH, respectively. + +1. Press Enter + +#### Create a branch to work on + +It is STRONGLY recommended to create your own development branch instead of working directly with a fork of the main branch: + +1. Navigate into the cloned CHAP repository directory: + ```bash + $ cd ChessAnalysisPipeline + ``` + +2. Create your development branch: + ```bash + $ git branch BRANCH-NAME + $ git checkout BRANCH-NAME + ``` + after choosing a suitable name for BRANCH-NAME, e.g., "dev_". + +3. Create and track a copy of your newly created branch on your forked remote repository: + ```bash + $ git push --set-upstream origin BRANCH-NAME + ``` + +#### Make and push changes + +You can now add to or make changes to the code or documentation. + +When you're ready to submit your changes, stage and commit your changes and push your changes to your forked remote repository on Github. +Best practice principles teach us to keep changes small, incremental and as logically grouped as possible within individual commits. There is no limit to the number of commits in any single pull request and it is much easier to review changes that are split across multiple commits. + +Stage any files that are changed or added to be committed by executing: +```bash +$ git add +``` +telling Git what to include in the next commit. When ready, commit these changes with: +```bash +$ git commit -m "a short description of the change" +``` +and push your locally saved changes to your forked remote repository on Github: +```bash +$ git push +``` + +(make_chap_pull_request)= +#### Make a pull request + +Making a pull request is the final step in contributing directly to the CHAP code base. After making changes or adding features to the code or documentation and pushing them to your forked remote Github repository you have to make a request to the CHAP administrators to have them included or "pulled" into the main code base. + +To do return to your web browser and navigate again to the [CHAP repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub. Then: + +1. You may see a banner indicating that your branch is ahead of the main CHAP branch or you may have to select your branch from the pull down box in the top left corner. Click the "contribute" button and the then the green "Open a pull request" button. + +1. After Github brings you to the pull request interface: + + a. Verify on the top that the base repository is CHESSComputing/ChessAnalysisPipeline and its base is "main", that the head repository is your branch on your forked repository and that Github display "Able to merge" in green right underneath this (contact the CHAP administrators if Github is not able to merge the changes). + + b. Add a clear and descriptive title for your pull request in the "Add a title" box. + + c. Add a clear description of your changes or additions "Add a description" +e" box. Making the title and description clear and consise will greatly help the administrators to determine whether your contribution is useful and needed for everyone to be included in the main code base. + + d. Click the green "Create pull request" button. + +## Code review process + +After submitting a pull request, changes will be reviewed by the administrators. Once approved, the pull request will be merged by the administrators and you can update your local branch by: + +1. Navigating in your web browser to your forked CHAP repository. + +1. Selecting your forked main branch from the pull down list on the top left, which should then say that it is ahead of CHESSComputing/ChessAnalysisPipeline:main. + +1. Click the "Sync fork" button to synchronize or update your local main branch with that on the main CHAP repository. + +1. Returning to your Terminal, navigating to the directory containing the clone of your forked repository and: + + a. Changing to your local main branch and pulling the updated remote one: + ```bash + $ git checkout main + $ git pull + ``` + + b. Changing to your local development branch and merging the chamges from the main branch into your local development branch: + ```bash + $ git checkout BRANCH-NAME + $ git merge main + ``` + +At this point, you are fully synchronized with the main CHAP code base, ready for a new cycle of making and submitting changes. + + +Please, check the [Github documentation](https://docs.github.com/en) on [creating your own personal account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github), [adding an SSH key to your account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account), [creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue), [forking a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo), or [submitting a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) for additional helpful hints. diff --git a/docs/index.rst b/docs/index.rst index dc243a67..ad78c2d2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,12 @@ Chess Analysis Pipeline (CHAP) introduction +.. toctree:: + :titlesonly: + :caption: Contributions + + CONTRIBUTIONS + .. toctree:: :titlesonly: :caption: Installation diff --git a/docs/workflows/EDD.md b/docs/workflows/EDD.md index 55d7636d..d6d72fae 100644 --- a/docs/workflows/EDD.md +++ b/docs/workflows/EDD.md @@ -468,7 +468,7 @@ $$ \frac{1}{d_{hkl}} = \frac{2m\sin(\theta)}{hc} j_{hkl} + \frac{2b\sin(\theta)}{hc} = m'j_{hkl}+b' $$ -which says that given a set of known Bragg peaks corresponding to lattice spacings $d_{hkl}$ occuring at channel indices $j_{hkl}$, a linear fit will uniquely determine $m'$ and $b'$. For a known takeoff angle $2\theta$, this uniquely determines $m$ and $b$ as well. Note that this also implies that without an accurately known value of $2`theta$, one *cannot* uniquely determine $m$ and $b$ from Bragg diffraction alone! +which says that given a set of known Bragg peaks corresponding to lattice spacings $d_{hkl}$ occuring at channel indices $j_{hkl}$, a linear fit will uniquely determine $m'$ and $b'$. For a known takeoff angle $2\theta$, this uniquely determines $m$ and $b$ as well. Note that this also implies that without an accurately known value of $2\theta$, one *cannot* uniquely determine $m$ and $b$ from Bragg diffraction alone! This leads to the above mentioned two-step detector channel energy calibration procedure: From 8b9d406fa2701e4404059c15f09d1d4814a5829e Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 10 Jun 2026 15:18:22 -0400 Subject: [PATCH 09/23] doc: fixed the contribution path in readme --- README.md | 2 +- docs/CONTRIBUTIONS.md | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 43434bde..8b49fe86 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,6 @@ Documentation for the latest release version can be found on [this project's git We welcome feedback, suggestions, issues and bug reports. Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. -When submitting an issue, please have a look at the [contribution guidelines](https://chesscomputing.github.io/ChessAnalysisPipeline/contributions.html). Following these guidelines grately helps us to address each issue promptly and effectively. +When submitting an issue, please have a look at the [contribution guidelines](https://chesscomputing.github.io/ChessAnalysisPipeline/CONTRIBUTIONS.html). Following these guidelines grately helps us to address each issue promptly and effectively. We appreciate your support! diff --git a/docs/CONTRIBUTIONS.md b/docs/CONTRIBUTIONS.md index 01786f03..c88551fb 100644 --- a/docs/CONTRIBUTIONS.md +++ b/docs/CONTRIBUTIONS.md @@ -1,8 +1,6 @@ (contributions)= # Contributions -RV CONTRIBUTING.md should be in your root directory - We welcome feedback, suggestions, issues and bug reports. Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. From 58a8110c1213844851348a10c1d0b0c4f635c462 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 24 Jun 2026 10:44:18 -0400 Subject: [PATCH 10/23] build: updated the deployment actions --- .github/workflows/manual-pages-deploy.yml | 4 +++- .github/workflows/pages-deploy.yml | 16 +++++++++------- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/.github/workflows/manual-pages-deploy.yml b/.github/workflows/manual-pages-deploy.yml index 5cd3b985..0539a33a 100644 --- a/.github/workflows/manual-pages-deploy.yml +++ b/.github/workflows/manual-pages-deploy.yml @@ -11,7 +11,9 @@ jobs: build_and_deploy: runs-on: ubuntu-latest permissions: - contents: write + contents: read + pages: write + id-token: write steps: - name: Checkout repository uses: actions/checkout@v4 diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml index 66c2c8d9..b2ecfa2c 100644 --- a/.github/workflows/pages-deploy.yml +++ b/.github/workflows/pages-deploy.yml @@ -1,13 +1,13 @@ name: Deploy Sphinx documentation to Pages -on: - push: - tags: - - v*.*.* #on: # push: -# branches: -# - docs +# tags: +# - v*.*.* +on: + push: + branches: + - docs defaults: run: @@ -17,7 +17,9 @@ jobs: build_and_deploy: runs-on: ubuntu-latest permissions: - contents: write + contents: read + pages: write + id-token: write steps: - name: Checkout repository uses: actions/checkout@v4 From 53d9c37ff3923e04e65f4a673fa4ea06c9d6f71f Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 24 Jun 2026 11:06:00 -0400 Subject: [PATCH 11/23] build: added a specific doc push deploy pages action --- .github/workflows/pages-deploy-from-docs.yml | 83 ++++++++++++++++++++ .github/workflows/pages-deploy.yml | 10 +-- 2 files changed, 86 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/pages-deploy-from-docs.yml diff --git a/.github/workflows/pages-deploy-from-docs.yml b/.github/workflows/pages-deploy-from-docs.yml new file mode 100644 index 00000000..1bed720d --- /dev/null +++ b/.github/workflows/pages-deploy-from-docs.yml @@ -0,0 +1,83 @@ +name: Deploy Sphinx documentation to Pages from docs branch push + +on: + push: + branches: + - docs + +defaults: + run: + shell: bash -l {0} + +jobs: + build_and_deploy: + runs-on: ubuntu-latest + permissions: + contents: read + pages: write + id-token: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Fetch Latest Tag + id: find_tag + run: | + LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "0.0.0") + CLEAN_VERSION=$(echo "$LATEST_TAG" | sed 's/^v//') + echo "version=$CLEAN_VERSION" >> $GITHUB_OUTPUT + + - name: Update docs configuration with version (tag) name + run: | + sed -i "s/PACKAGE_VERSION/${{ steps.find_tag.outputs.version}}/" setup.py + sed -i "s/PACKAGE_VERSION/${{ steps.find_tag.outputs.version}}/" CHAP/__init__.py + sed -i "s/PACKAGE_VERSION/${{ steps.find_tag.outputs.version}}/" docs/conf.py + sed -i "s/PACKAGE_VERSION/${{ steps.find_tag.outputs.version}}/" docs/installation.md + cat setup.py + + - name: Setup Miniconda + uses: conda-incubator/setup-miniconda@v3 + with: + python-version: '3.10' + environment-file: docs/environment.yml + auto-activate: true + activate-environment: sphinx + conda-remove-defaults: true + use-mamba: true + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install sphinx + pip install sphinx-math-dollar + pip install sphinx-rtd-theme + pip install myst-parser + #pip install autodoc_pydantic + + - name: Install package + run: | + pip install -e . + conda list + + - name: Generate .rst files with sphinx-apidoc + run: | + sphinx-apidoc -M --tocfile api_documentation --module-first -o docs CHAP CHAP/hdrm CHAP/inference CHAP/sin2psi CHAP/test + + - name: Build Sphinx HTML documentation + run: | + make clean + make html + working-directory: ./docs + + - name: List generated files + run: | + pwd + ls -lha + find ./docs/_build/html -type f + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html + diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml index b2ecfa2c..b81fc366 100644 --- a/.github/workflows/pages-deploy.yml +++ b/.github/workflows/pages-deploy.yml @@ -1,13 +1,9 @@ -name: Deploy Sphinx documentation to Pages +name: Deploy Sphinx documentation to Pages from tagged release -#on: -# push: -# tags: -# - v*.*.* on: push: - branches: - - docs + tags: + - v*.*.* defaults: run: From 16bfb5e65eb5403d8192acc884d8a3c76719f696 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 24 Jun 2026 11:12:23 -0400 Subject: [PATCH 12/23] build: set permission/contents to write inactions --- .github/workflows/manual-pages-deploy.yml | 2 +- .github/workflows/pages-deploy-from-docs.yml | 2 +- .github/workflows/pages-deploy.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/manual-pages-deploy.yml b/.github/workflows/manual-pages-deploy.yml index 0539a33a..489fa7e1 100644 --- a/.github/workflows/manual-pages-deploy.yml +++ b/.github/workflows/manual-pages-deploy.yml @@ -11,7 +11,7 @@ jobs: build_and_deploy: runs-on: ubuntu-latest permissions: - contents: read + contents: write pages: write id-token: write steps: diff --git a/.github/workflows/pages-deploy-from-docs.yml b/.github/workflows/pages-deploy-from-docs.yml index 1bed720d..a1903e92 100644 --- a/.github/workflows/pages-deploy-from-docs.yml +++ b/.github/workflows/pages-deploy-from-docs.yml @@ -13,7 +13,7 @@ jobs: build_and_deploy: runs-on: ubuntu-latest permissions: - contents: read + contents: write pages: write id-token: write steps: diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml index b81fc366..e5b7f5e6 100644 --- a/.github/workflows/pages-deploy.yml +++ b/.github/workflows/pages-deploy.yml @@ -13,7 +13,7 @@ jobs: build_and_deploy: runs-on: ubuntu-latest permissions: - contents: read + contents: write pages: write id-token: write steps: From e2ff5d976a681476574b1c7b3fcc802111b59a90 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 24 Jun 2026 11:26:09 -0400 Subject: [PATCH 13/23] build: change tag for deploy pages from docs push --- .github/workflows/manual-pages-deploy.yml | 1 + .github/workflows/pages-deploy-from-docs.yml | 15 ++++----------- .github/workflows/pages-deploy.yml | 1 + 3 files changed, 6 insertions(+), 11 deletions(-) diff --git a/.github/workflows/manual-pages-deploy.yml b/.github/workflows/manual-pages-deploy.yml index 489fa7e1..06ebd89d 100644 --- a/.github/workflows/manual-pages-deploy.yml +++ b/.github/workflows/manual-pages-deploy.yml @@ -24,6 +24,7 @@ jobs: sed -i "s/PACKAGE_VERSION/0.0.1/" CHAP/__init__.py sed -i "s/PACKAGE_VERSION/0.0.1/" docs/conf.py sed -i "s/PACKAGE_VERSION/0.0.1/" docs/installation.md + cat setup.py - name: Setup Miniconda uses: conda-incubator/setup-miniconda@v3 diff --git a/.github/workflows/pages-deploy-from-docs.yml b/.github/workflows/pages-deploy-from-docs.yml index a1903e92..44d987c7 100644 --- a/.github/workflows/pages-deploy-from-docs.yml +++ b/.github/workflows/pages-deploy-from-docs.yml @@ -20,19 +20,12 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 - - name: Fetch Latest Tag - id: find_tag - run: | - LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "0.0.0") - CLEAN_VERSION=$(echo "$LATEST_TAG" | sed 's/^v//') - echo "version=$CLEAN_VERSION" >> $GITHUB_OUTPUT - - name: Update docs configuration with version (tag) name run: | - sed -i "s/PACKAGE_VERSION/${{ steps.find_tag.outputs.version}}/" setup.py - sed -i "s/PACKAGE_VERSION/${{ steps.find_tag.outputs.version}}/" CHAP/__init__.py - sed -i "s/PACKAGE_VERSION/${{ steps.find_tag.outputs.version}}/" docs/conf.py - sed -i "s/PACKAGE_VERSION/${{ steps.find_tag.outputs.version}}/" docs/installation.md + sed -i "s/PACKAGE_VERSION/0.0.1/" setup.py + sed -i "s/PACKAGE_VERSION/0.0.1/" CHAP/__init__.py + sed -i "s/PACKAGE_VERSION/0.0.1/" docs/conf.py + sed -i "s/PACKAGE_VERSION/0.0.1/" docs/installation.md cat setup.py - name: Setup Miniconda diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml index e5b7f5e6..db31d585 100644 --- a/.github/workflows/pages-deploy.yml +++ b/.github/workflows/pages-deploy.yml @@ -26,6 +26,7 @@ jobs: sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" CHAP/__init__.py sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" docs/conf.py sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" docs/installation.md + cat setup.py - name: Setup Miniconda uses: conda-incubator/setup-miniconda@v3 From 9438771d526d351a0e121ba183e03a7ea20b649b Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 24 Jun 2026 11:43:51 -0400 Subject: [PATCH 14/23] build: try fix ghpages instead of readme --- .github/workflows/manual-pages-deploy.yml | 2 +- .github/workflows/pages-deploy-from-docs.yml | 2 +- .github/workflows/pages-deploy.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/manual-pages-deploy.yml b/.github/workflows/manual-pages-deploy.yml index 06ebd89d..7d284c66 100644 --- a/.github/workflows/manual-pages-deploy.yml +++ b/.github/workflows/manual-pages-deploy.yml @@ -23,7 +23,6 @@ jobs: sed -i "s/PACKAGE_VERSION/0.0.1/" setup.py sed -i "s/PACKAGE_VERSION/0.0.1/" CHAP/__init__.py sed -i "s/PACKAGE_VERSION/0.0.1/" docs/conf.py - sed -i "s/PACKAGE_VERSION/0.0.1/" docs/installation.md cat setup.py - name: Setup Miniconda @@ -70,5 +69,6 @@ jobs: uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} + publish_branch: gh-pages publish_dir: ./docs/_build/html diff --git a/.github/workflows/pages-deploy-from-docs.yml b/.github/workflows/pages-deploy-from-docs.yml index 44d987c7..b79d6767 100644 --- a/.github/workflows/pages-deploy-from-docs.yml +++ b/.github/workflows/pages-deploy-from-docs.yml @@ -25,7 +25,6 @@ jobs: sed -i "s/PACKAGE_VERSION/0.0.1/" setup.py sed -i "s/PACKAGE_VERSION/0.0.1/" CHAP/__init__.py sed -i "s/PACKAGE_VERSION/0.0.1/" docs/conf.py - sed -i "s/PACKAGE_VERSION/0.0.1/" docs/installation.md cat setup.py - name: Setup Miniconda @@ -72,5 +71,6 @@ jobs: uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} + publish_branch: gh-pages publish_dir: ./docs/_build/html diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml index db31d585..8c58600c 100644 --- a/.github/workflows/pages-deploy.yml +++ b/.github/workflows/pages-deploy.yml @@ -25,7 +25,6 @@ jobs: sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" setup.py sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" CHAP/__init__.py sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" docs/conf.py - sed -i "s/PACKAGE_VERSION/${{ github.ref_name }}/" docs/installation.md cat setup.py - name: Setup Miniconda @@ -72,5 +71,6 @@ jobs: uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} + publish_branch: gh-pages publish_dir: ./docs/_build/html From b93bb293f036ddc09acf75fa8233cde8907a1427 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 24 Jun 2026 11:51:22 -0400 Subject: [PATCH 15/23] build: try fix ghpages instead of readme --- .github/workflows/manual-pages-deploy.yml | 1 - .github/workflows/pages-deploy-from-docs.yml | 1 - .github/workflows/pages-deploy.yml | 1 - 3 files changed, 3 deletions(-) diff --git a/.github/workflows/manual-pages-deploy.yml b/.github/workflows/manual-pages-deploy.yml index 7d284c66..af1840dc 100644 --- a/.github/workflows/manual-pages-deploy.yml +++ b/.github/workflows/manual-pages-deploy.yml @@ -69,6 +69,5 @@ jobs: uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_branch: gh-pages publish_dir: ./docs/_build/html diff --git a/.github/workflows/pages-deploy-from-docs.yml b/.github/workflows/pages-deploy-from-docs.yml index b79d6767..9d2fed0a 100644 --- a/.github/workflows/pages-deploy-from-docs.yml +++ b/.github/workflows/pages-deploy-from-docs.yml @@ -71,6 +71,5 @@ jobs: uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_branch: gh-pages publish_dir: ./docs/_build/html diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml index 8c58600c..c28558b7 100644 --- a/.github/workflows/pages-deploy.yml +++ b/.github/workflows/pages-deploy.yml @@ -71,6 +71,5 @@ jobs: uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_branch: gh-pages publish_dir: ./docs/_build/html From 7b88071b376fb5034b9c3905cdaab7191bac1d7d Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 24 Jun 2026 14:19:06 -0400 Subject: [PATCH 16/23] build: revert permissiones back to before updating deployment --- .github/workflows/manual-pages-deploy.yml | 2 -- .github/workflows/pages-deploy.yml | 4 +--- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/workflows/manual-pages-deploy.yml b/.github/workflows/manual-pages-deploy.yml index af1840dc..95895b9d 100644 --- a/.github/workflows/manual-pages-deploy.yml +++ b/.github/workflows/manual-pages-deploy.yml @@ -12,8 +12,6 @@ jobs: runs-on: ubuntu-latest permissions: contents: write - pages: write - id-token: write steps: - name: Checkout repository uses: actions/checkout@v4 diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml index c28558b7..fe0e79e4 100644 --- a/.github/workflows/pages-deploy.yml +++ b/.github/workflows/pages-deploy.yml @@ -1,4 +1,4 @@ -name: Deploy Sphinx documentation to Pages from tagged release +name: Deploy Sphinx documentation to Pages on: push: @@ -14,8 +14,6 @@ jobs: runs-on: ubuntu-latest permissions: contents: write - pages: write - id-token: write steps: - name: Checkout repository uses: actions/checkout@v4 From 3b1b19b0bd450a9d14c3e90ed9953260bda08953 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 24 Jun 2026 14:20:32 -0400 Subject: [PATCH 17/23] build: removes the docs branch push deployment --- .github/workflows/pages-deploy-from-docs.yml | 75 -------------------- 1 file changed, 75 deletions(-) delete mode 100644 .github/workflows/pages-deploy-from-docs.yml diff --git a/.github/workflows/pages-deploy-from-docs.yml b/.github/workflows/pages-deploy-from-docs.yml deleted file mode 100644 index 9d2fed0a..00000000 --- a/.github/workflows/pages-deploy-from-docs.yml +++ /dev/null @@ -1,75 +0,0 @@ -name: Deploy Sphinx documentation to Pages from docs branch push - -on: - push: - branches: - - docs - -defaults: - run: - shell: bash -l {0} - -jobs: - build_and_deploy: - runs-on: ubuntu-latest - permissions: - contents: write - pages: write - id-token: write - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Update docs configuration with version (tag) name - run: | - sed -i "s/PACKAGE_VERSION/0.0.1/" setup.py - sed -i "s/PACKAGE_VERSION/0.0.1/" CHAP/__init__.py - sed -i "s/PACKAGE_VERSION/0.0.1/" docs/conf.py - cat setup.py - - - name: Setup Miniconda - uses: conda-incubator/setup-miniconda@v3 - with: - python-version: '3.10' - environment-file: docs/environment.yml - auto-activate: true - activate-environment: sphinx - conda-remove-defaults: true - use-mamba: true - - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install sphinx - pip install sphinx-math-dollar - pip install sphinx-rtd-theme - pip install myst-parser - #pip install autodoc_pydantic - - - name: Install package - run: | - pip install -e . - conda list - - - name: Generate .rst files with sphinx-apidoc - run: | - sphinx-apidoc -M --tocfile api_documentation --module-first -o docs CHAP CHAP/hdrm CHAP/inference CHAP/sin2psi CHAP/test - - - name: Build Sphinx HTML documentation - run: | - make clean - make html - working-directory: ./docs - - - name: List generated files - run: | - pwd - ls -lha - find ./docs/_build/html -type f - - - name: Deploy to GitHub Pages - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./docs/_build/html - From 677f8010cdecdb60ede40239f8039fcab997a0aa Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 24 Jun 2026 14:39:20 -0400 Subject: [PATCH 18/23] build: try deploy fro doc branch again --- .github/workflows/pages-deploy-from-docs.yml | 74 ++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 .github/workflows/pages-deploy-from-docs.yml diff --git a/.github/workflows/pages-deploy-from-docs.yml b/.github/workflows/pages-deploy-from-docs.yml new file mode 100644 index 00000000..015979de --- /dev/null +++ b/.github/workflows/pages-deploy-from-docs.yml @@ -0,0 +1,74 @@ +name: Deploy Sphinx documentation to Pages from docs branch push + +on: + push: + branches: + - docs + +defaults: + run: + shell: bash -l {0} + +jobs: + build_and_deploy: + runs-on: ubuntu-latest + permissions: + contents: write + pages: write + id-token: write + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Update docs configuration with version (tag) name + run: | + sed -i "s/PACKAGE_VERSION/0.0.1/" setup.py + sed -i "s/PACKAGE_VERSION/0.0.1/" CHAP/__init__.py + sed -i "s/PACKAGE_VERSION/0.0.1/" docs/conf.py + cat setup.py + + - name: Setup Miniconda + uses: conda-incubator/setup-miniconda@v3 + with: + python-version: '3.10' + environment-file: docs/environment.yml + auto-activate: true + activate-environment: sphinx + conda-remove-defaults: true + use-mamba: true + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install sphinx + pip install sphinx-math-dollar + pip install sphinx-rtd-theme + pip install myst-parser + #pip install autodoc_pydantic + + - name: Install package + run: | + pip install -e . + conda list + + - name: Generate .rst files with sphinx-apidoc + run: | + sphinx-apidoc -M --tocfile api_documentation --module-first -o docs CHAP CHAP/hdrm CHAP/inference CHAP/sin2psi CHAP/test + + - name: Build Sphinx HTML documentation + run: | + make clean + make html + working-directory: ./docs + + - name: List generated files + run: | + pwd + ls -lha + find ./docs/_build/html -type f + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html From 817bb9847eb70aa657b9c37724cca29ef6524905 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Wed, 24 Jun 2026 15:21:58 -0400 Subject: [PATCH 19/23] build: try deploy from doc branch again --- .github/workflows/manual-pages-deploy.yml | 2 ++ .github/workflows/pages-deploy.yml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/.github/workflows/manual-pages-deploy.yml b/.github/workflows/manual-pages-deploy.yml index 95895b9d..af1840dc 100644 --- a/.github/workflows/manual-pages-deploy.yml +++ b/.github/workflows/manual-pages-deploy.yml @@ -12,6 +12,8 @@ jobs: runs-on: ubuntu-latest permissions: contents: write + pages: write + id-token: write steps: - name: Checkout repository uses: actions/checkout@v4 diff --git a/.github/workflows/pages-deploy.yml b/.github/workflows/pages-deploy.yml index fe0e79e4..d4c09044 100644 --- a/.github/workflows/pages-deploy.yml +++ b/.github/workflows/pages-deploy.yml @@ -14,6 +14,8 @@ jobs: runs-on: ubuntu-latest permissions: contents: write + pages: write + id-token: write steps: - name: Checkout repository uses: actions/checkout@v4 From 924f14a08cd6d54b09cee6bae41c510ee8de4986 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Tue, 30 Jun 2026 14:41:02 -0400 Subject: [PATCH 20/23] build: try deploy from doc branch again --- .github/workflows/pages-deploy-from-docs.yml | 3 ++- docs/CONTRIBUTIONS.md | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pages-deploy-from-docs.yml b/.github/workflows/pages-deploy-from-docs.yml index 015979de..56e58af2 100644 --- a/.github/workflows/pages-deploy-from-docs.yml +++ b/.github/workflows/pages-deploy-from-docs.yml @@ -65,7 +65,8 @@ jobs: run: | pwd ls -lha - find ./docs/_build/html -type f + ls -lha ./docs/_build/html + cat ./docs/_build/html/index.html - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 diff --git a/docs/CONTRIBUTIONS.md b/docs/CONTRIBUTIONS.md index c88551fb..3236f8e3 100644 --- a/docs/CONTRIBUTIONS.md +++ b/docs/CONTRIBUTIONS.md @@ -1,6 +1,8 @@ (contributions)= # Contributions +A small change to debug deployment + We welcome feedback, suggestions, issues and bug reports. Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. From e3a2ef0528db957cca0f4137ad041dcc6f4c8c82 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Tue, 30 Jun 2026 15:07:50 -0400 Subject: [PATCH 21/23] build: try deploy from doc branch again --- README.md | 6 -- docs/CONTRIBUTIONS.md | 236 ------------------------------------------ docs/index.rst | 6 -- 3 files changed, 248 deletions(-) delete mode 100644 docs/CONTRIBUTIONS.md diff --git a/README.md b/README.md index 8b49fe86..64c48fc2 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,4 @@ There are several subpackages within CHAP that contain specialized items to hand ## :books: Documentation Documentation for the latest release version can be found on [this project's github pages site](https://chesscomputing.github.io/ChessAnalysisPipeline/). -## :handshake: Contributing -We welcome feedback, suggestions, issues and bug reports. - -Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. -When submitting an issue, please have a look at the [contribution guidelines](https://chesscomputing.github.io/ChessAnalysisPipeline/CONTRIBUTIONS.html). Following these guidelines grately helps us to address each issue promptly and effectively. - We appreciate your support! diff --git a/docs/CONTRIBUTIONS.md b/docs/CONTRIBUTIONS.md deleted file mode 100644 index 3236f8e3..00000000 --- a/docs/CONTRIBUTIONS.md +++ /dev/null @@ -1,236 +0,0 @@ -(contributions)= -# Contributions - -A small change to debug deployment - -We welcome feedback, suggestions, issues and bug reports. - -Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. - -We appreciate your support! - -## How to contribute - -CHAP is an open source project and we encourage and gratefully receive feedback or contributions to improve our product. Please follow these guidelines to contribute to CHAP. Doing so grately helps us to address each contribution promptly and effectively. - -There are many ways to contribute, from supplying examples, improving the documentation, submitting bug reports and feature requests or writing code that can be incorporated into CHAP itself. -Please [submit an issue](submit_chap_issue) to report a bug or request new features. Actual bug fixes or other types of contributions to the source code or documentation should be submitted after [creating a fork](create_chap_fork) and making a [pull request](make_chap_pull_request). Please do not use the issue tracker for support questions or to leave feedback. Instead, feel free to contact any of the administators directly. - -Please only report a bug or request a new feature after checking the [existing open issues](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) and verifying that it has not yet been reported, requested or addressed! - -(submit_chap_issue)= -### Submitting an issue - -If you find a security vulnerability, do NOT open an issue. Contact any of the administators instead. - -#### Reporting a bug - -Report a bug by following these step to submit an issue: - -1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. - -1. Select the "CHAP CLI Bug report" option to open a template to provide us with information to help us track and reproduce the error. - -1. After the "CHAP CLI Bug report" interface opens: - - a. Supply a clear and concise title to identify the issue. - - b. Edit and fill out the description form, being as specific as you can in answering each of the following items: - - - Give a clear and concise description of the nature of the bug. - - - Provide a minimal pipeline configuration in which the bug appears. - - - Describe what you expected to happen. - - - Describe what actually happens and if possible add a record or a screen shot of the (relevant part of the) CHAP logger output to show the error or explain the problem. - - - Provide information of the OS, CHAP version and python/conda environment. - - - Provide any additional information that can help in tracking down the issue. - - c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. - -#### Suggesting or requesting a new feature or enhancement - -Request a new feature by following these step to submit an issue: - -1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. - -1. Select the "New PipelineItem request" option to open a template to provide us with information that helps us to modify existing or create new CHAP `PipelineItem`s to implement the feature. - -1. After the "New PipelineItem request" dialogue interface opens: - - a. Supply a clear and concise title to describe the feature. - - b. Edit and fill out the description form, being as specific as you can in answering each of the following items: - - - Describe the intended use of the requested feature. - - - Describe the feature's inputs. - - - Describe the feature's optional interaction points. - - - Describe the feature's output. - - - Provide any additional information that can help in implementing the new feature. - - c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. - -#### Reporting any other issue - -Follow these these step to submit any other issue, not covered by either option above: - -1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. - -1. Select the "Blank issue" option to open a template to provide us with information to help us resolve the issue. - -1. After the new issue interface opens: - - a. Supply a clear and concise title to identify the issue, - - b. Edit and fill out the description form, being as specific as you can. - - c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. - -Check out the [Github documentation](https://docs.github.com/en) on [creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue) for additional helpful hints. - -### Directly contributing to the source code or documentation - -Actual bug fixes or other types of contributions to the source code or documentation should be submitted by making a pull request from your own fork. -Whether you are fixing bugs, adding features, or improving documentation, following the steps below ensures that any contributions can be verified and vetted by the administrators before incorporation into the main code base. To contribute directly to CHAP, you will need your own account on [Github](https://github.com). - -(create_chap_fork)= -#### Create your own fork - -Start by creating your own copy or "fork" of the CHAP repository before starting to contribute directly to the source code or documentation. This creates a copy of the repository that shares the code and documentation with the original CHAP repository, but that lets you make modifications or additions without directly affecting the source. - -Create a fork by following these steps: - -1. In a web browser, navigate to the [CHAP repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub. - -1. In the top-right corner of the page, click "Fork". - -1. After the "Create a new fork" interface opens: - - a. Select your own personal Github account under "Choose an owner". By default, forks are named the same as their upstream repositories. To follow this convention, leave the Repository name unchanged as "ChessAnalysisPipeline". - - b. Optionally, in the "Description" field, type a description of your fork. - - c. It is strongly recommended to select "Copy the main branch only" (its default setting). - - d. Click on the green "Create fork" button. - -#### Clone your fork to your computer - -After creating your own CHAP fork, you also need to create a local copy of the project or "clone" on your own computer. To clone your forked repositiory: - -1. Click on the green "<> Code" botton. - -1. Copy the URL for the repository: Under the "Local" tab choose to clone the repository using HTTPS or using an SSH key by selecting the respective tab and clicking the "Copy URL to clipboard" button to the right of the corresponding link. Choose HTTPS for a fast and easy setup if you just want to inspect the code base. Choose SSH if you plan to contribute frequently and want to avoid needing to enter your credentials for every push or pull. - -1. On Mac or Linux, open a Terminal. On Windows, open Git Bash. - -1. Change to the location where you want the cloned directory. - -1. Type git clone, and then paste the URL you copied earlier. It should look like: - ```bash - $ git clone https://github.com//ChessAnalysisPipeline.git - ``` - or - ```bash - $ git clone git@github.com:/ChessAnalysisPipeline.git - ``` - for cloning with HTTPS or SSH, respectively. - -1. Press Enter - -#### Create a branch to work on - -It is STRONGLY recommended to create your own development branch instead of working directly with a fork of the main branch: - -1. Navigate into the cloned CHAP repository directory: - ```bash - $ cd ChessAnalysisPipeline - ``` - -2. Create your development branch: - ```bash - $ git branch BRANCH-NAME - $ git checkout BRANCH-NAME - ``` - after choosing a suitable name for BRANCH-NAME, e.g., "dev_". - -3. Create and track a copy of your newly created branch on your forked remote repository: - ```bash - $ git push --set-upstream origin BRANCH-NAME - ``` - -#### Make and push changes - -You can now add to or make changes to the code or documentation. - -When you're ready to submit your changes, stage and commit your changes and push your changes to your forked remote repository on Github. -Best practice principles teach us to keep changes small, incremental and as logically grouped as possible within individual commits. There is no limit to the number of commits in any single pull request and it is much easier to review changes that are split across multiple commits. - -Stage any files that are changed or added to be committed by executing: -```bash -$ git add -``` -telling Git what to include in the next commit. When ready, commit these changes with: -```bash -$ git commit -m "a short description of the change" -``` -and push your locally saved changes to your forked remote repository on Github: -```bash -$ git push -``` - -(make_chap_pull_request)= -#### Make a pull request - -Making a pull request is the final step in contributing directly to the CHAP code base. After making changes or adding features to the code or documentation and pushing them to your forked remote Github repository you have to make a request to the CHAP administrators to have them included or "pulled" into the main code base. - -To do return to your web browser and navigate again to the [CHAP repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub. Then: - -1. You may see a banner indicating that your branch is ahead of the main CHAP branch or you may have to select your branch from the pull down box in the top left corner. Click the "contribute" button and the then the green "Open a pull request" button. - -1. After Github brings you to the pull request interface: - - a. Verify on the top that the base repository is CHESSComputing/ChessAnalysisPipeline and its base is "main", that the head repository is your branch on your forked repository and that Github display "Able to merge" in green right underneath this (contact the CHAP administrators if Github is not able to merge the changes). - - b. Add a clear and descriptive title for your pull request in the "Add a title" box. - - c. Add a clear description of your changes or additions "Add a description" -e" box. Making the title and description clear and consise will greatly help the administrators to determine whether your contribution is useful and needed for everyone to be included in the main code base. - - d. Click the green "Create pull request" button. - -## Code review process - -After submitting a pull request, changes will be reviewed by the administrators. Once approved, the pull request will be merged by the administrators and you can update your local branch by: - -1. Navigating in your web browser to your forked CHAP repository. - -1. Selecting your forked main branch from the pull down list on the top left, which should then say that it is ahead of CHESSComputing/ChessAnalysisPipeline:main. - -1. Click the "Sync fork" button to synchronize or update your local main branch with that on the main CHAP repository. - -1. Returning to your Terminal, navigating to the directory containing the clone of your forked repository and: - - a. Changing to your local main branch and pulling the updated remote one: - ```bash - $ git checkout main - $ git pull - ``` - - b. Changing to your local development branch and merging the chamges from the main branch into your local development branch: - ```bash - $ git checkout BRANCH-NAME - $ git merge main - ``` - -At this point, you are fully synchronized with the main CHAP code base, ready for a new cycle of making and submitting changes. - - -Please, check the [Github documentation](https://docs.github.com/en) on [creating your own personal account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github), [adding an SSH key to your account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account), [creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue), [forking a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo), or [submitting a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) for additional helpful hints. diff --git a/docs/index.rst b/docs/index.rst index ad78c2d2..dc243a67 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,12 +7,6 @@ Chess Analysis Pipeline (CHAP) introduction -.. toctree:: - :titlesonly: - :caption: Contributions - - CONTRIBUTIONS - .. toctree:: :titlesonly: :caption: Installation From 114dd14567cf95d5415cb85daca7d841ab032787 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Tue, 7 Jul 2026 12:39:39 -0400 Subject: [PATCH 22/23] build: try deploy from doc branch again Restore CONTRIBUTIONS --- README.md | 6 ++ docs/CONTRIBUTIONS.md | 236 ++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 6 ++ 3 files changed, 248 insertions(+) create mode 100644 docs/CONTRIBUTIONS.md diff --git a/README.md b/README.md index 64c48fc2..8b49fe86 100644 --- a/README.md +++ b/README.md @@ -16,4 +16,10 @@ There are several subpackages within CHAP that contain specialized items to hand ## :books: Documentation Documentation for the latest release version can be found on [this project's github pages site](https://chesscomputing.github.io/ChessAnalysisPipeline/). +## :handshake: Contributing +We welcome feedback, suggestions, issues and bug reports. + +Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. +When submitting an issue, please have a look at the [contribution guidelines](https://chesscomputing.github.io/ChessAnalysisPipeline/CONTRIBUTIONS.html). Following these guidelines grately helps us to address each issue promptly and effectively. + We appreciate your support! diff --git a/docs/CONTRIBUTIONS.md b/docs/CONTRIBUTIONS.md new file mode 100644 index 00000000..3236f8e3 --- /dev/null +++ b/docs/CONTRIBUTIONS.md @@ -0,0 +1,236 @@ +(contributions)= +# Contributions + +A small change to debug deployment + +We welcome feedback, suggestions, issues and bug reports. + +Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve. + +We appreciate your support! + +## How to contribute + +CHAP is an open source project and we encourage and gratefully receive feedback or contributions to improve our product. Please follow these guidelines to contribute to CHAP. Doing so grately helps us to address each contribution promptly and effectively. + +There are many ways to contribute, from supplying examples, improving the documentation, submitting bug reports and feature requests or writing code that can be incorporated into CHAP itself. +Please [submit an issue](submit_chap_issue) to report a bug or request new features. Actual bug fixes or other types of contributions to the source code or documentation should be submitted after [creating a fork](create_chap_fork) and making a [pull request](make_chap_pull_request). Please do not use the issue tracker for support questions or to leave feedback. Instead, feel free to contact any of the administators directly. + +Please only report a bug or request a new feature after checking the [existing open issues](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) and verifying that it has not yet been reported, requested or addressed! + +(submit_chap_issue)= +### Submitting an issue + +If you find a security vulnerability, do NOT open an issue. Contact any of the administators instead. + +#### Reporting a bug + +Report a bug by following these step to submit an issue: + +1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. + +1. Select the "CHAP CLI Bug report" option to open a template to provide us with information to help us track and reproduce the error. + +1. After the "CHAP CLI Bug report" interface opens: + + a. Supply a clear and concise title to identify the issue. + + b. Edit and fill out the description form, being as specific as you can in answering each of the following items: + + - Give a clear and concise description of the nature of the bug. + + - Provide a minimal pipeline configuration in which the bug appears. + + - Describe what you expected to happen. + + - Describe what actually happens and if possible add a record or a screen shot of the (relevant part of the) CHAP logger output to show the error or explain the problem. + + - Provide information of the OS, CHAP version and python/conda environment. + + - Provide any additional information that can help in tracking down the issue. + + c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. + +#### Suggesting or requesting a new feature or enhancement + +Request a new feature by following these step to submit an issue: + +1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. + +1. Select the "New PipelineItem request" option to open a template to provide us with information that helps us to modify existing or create new CHAP `PipelineItem`s to implement the feature. + +1. After the "New PipelineItem request" dialogue interface opens: + + a. Supply a clear and concise title to describe the feature. + + b. Edit and fill out the description form, being as specific as you can in answering each of the following items: + + - Describe the intended use of the requested feature. + + - Describe the feature's inputs. + + - Describe the feature's optional interaction points. + + - Describe the feature's output. + + - Provide any additional information that can help in implementing the new feature. + + c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. + +#### Reporting any other issue + +Follow these these step to submit any other issue, not covered by either option above: + +1. Click on the green "New issues" botton on the [issues tab of the CHAP Github repository](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues) to open a new issue. + +1. Select the "Blank issue" option to open a template to provide us with information to help us resolve the issue. + +1. After the new issue interface opens: + + a. Supply a clear and concise title to identify the issue, + + b. Edit and fill out the description form, being as specific as you can. + + c. Click on the green "Create" botton on the right bottom corner of the dialogue interface. + +Check out the [Github documentation](https://docs.github.com/en) on [creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue) for additional helpful hints. + +### Directly contributing to the source code or documentation + +Actual bug fixes or other types of contributions to the source code or documentation should be submitted by making a pull request from your own fork. +Whether you are fixing bugs, adding features, or improving documentation, following the steps below ensures that any contributions can be verified and vetted by the administrators before incorporation into the main code base. To contribute directly to CHAP, you will need your own account on [Github](https://github.com). + +(create_chap_fork)= +#### Create your own fork + +Start by creating your own copy or "fork" of the CHAP repository before starting to contribute directly to the source code or documentation. This creates a copy of the repository that shares the code and documentation with the original CHAP repository, but that lets you make modifications or additions without directly affecting the source. + +Create a fork by following these steps: + +1. In a web browser, navigate to the [CHAP repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub. + +1. In the top-right corner of the page, click "Fork". + +1. After the "Create a new fork" interface opens: + + a. Select your own personal Github account under "Choose an owner". By default, forks are named the same as their upstream repositories. To follow this convention, leave the Repository name unchanged as "ChessAnalysisPipeline". + + b. Optionally, in the "Description" field, type a description of your fork. + + c. It is strongly recommended to select "Copy the main branch only" (its default setting). + + d. Click on the green "Create fork" button. + +#### Clone your fork to your computer + +After creating your own CHAP fork, you also need to create a local copy of the project or "clone" on your own computer. To clone your forked repositiory: + +1. Click on the green "<> Code" botton. + +1. Copy the URL for the repository: Under the "Local" tab choose to clone the repository using HTTPS or using an SSH key by selecting the respective tab and clicking the "Copy URL to clipboard" button to the right of the corresponding link. Choose HTTPS for a fast and easy setup if you just want to inspect the code base. Choose SSH if you plan to contribute frequently and want to avoid needing to enter your credentials for every push or pull. + +1. On Mac or Linux, open a Terminal. On Windows, open Git Bash. + +1. Change to the location where you want the cloned directory. + +1. Type git clone, and then paste the URL you copied earlier. It should look like: + ```bash + $ git clone https://github.com//ChessAnalysisPipeline.git + ``` + or + ```bash + $ git clone git@github.com:/ChessAnalysisPipeline.git + ``` + for cloning with HTTPS or SSH, respectively. + +1. Press Enter + +#### Create a branch to work on + +It is STRONGLY recommended to create your own development branch instead of working directly with a fork of the main branch: + +1. Navigate into the cloned CHAP repository directory: + ```bash + $ cd ChessAnalysisPipeline + ``` + +2. Create your development branch: + ```bash + $ git branch BRANCH-NAME + $ git checkout BRANCH-NAME + ``` + after choosing a suitable name for BRANCH-NAME, e.g., "dev_". + +3. Create and track a copy of your newly created branch on your forked remote repository: + ```bash + $ git push --set-upstream origin BRANCH-NAME + ``` + +#### Make and push changes + +You can now add to or make changes to the code or documentation. + +When you're ready to submit your changes, stage and commit your changes and push your changes to your forked remote repository on Github. +Best practice principles teach us to keep changes small, incremental and as logically grouped as possible within individual commits. There is no limit to the number of commits in any single pull request and it is much easier to review changes that are split across multiple commits. + +Stage any files that are changed or added to be committed by executing: +```bash +$ git add +``` +telling Git what to include in the next commit. When ready, commit these changes with: +```bash +$ git commit -m "a short description of the change" +``` +and push your locally saved changes to your forked remote repository on Github: +```bash +$ git push +``` + +(make_chap_pull_request)= +#### Make a pull request + +Making a pull request is the final step in contributing directly to the CHAP code base. After making changes or adding features to the code or documentation and pushing them to your forked remote Github repository you have to make a request to the CHAP administrators to have them included or "pulled" into the main code base. + +To do return to your web browser and navigate again to the [CHAP repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub. Then: + +1. You may see a banner indicating that your branch is ahead of the main CHAP branch or you may have to select your branch from the pull down box in the top left corner. Click the "contribute" button and the then the green "Open a pull request" button. + +1. After Github brings you to the pull request interface: + + a. Verify on the top that the base repository is CHESSComputing/ChessAnalysisPipeline and its base is "main", that the head repository is your branch on your forked repository and that Github display "Able to merge" in green right underneath this (contact the CHAP administrators if Github is not able to merge the changes). + + b. Add a clear and descriptive title for your pull request in the "Add a title" box. + + c. Add a clear description of your changes or additions "Add a description" +e" box. Making the title and description clear and consise will greatly help the administrators to determine whether your contribution is useful and needed for everyone to be included in the main code base. + + d. Click the green "Create pull request" button. + +## Code review process + +After submitting a pull request, changes will be reviewed by the administrators. Once approved, the pull request will be merged by the administrators and you can update your local branch by: + +1. Navigating in your web browser to your forked CHAP repository. + +1. Selecting your forked main branch from the pull down list on the top left, which should then say that it is ahead of CHESSComputing/ChessAnalysisPipeline:main. + +1. Click the "Sync fork" button to synchronize or update your local main branch with that on the main CHAP repository. + +1. Returning to your Terminal, navigating to the directory containing the clone of your forked repository and: + + a. Changing to your local main branch and pulling the updated remote one: + ```bash + $ git checkout main + $ git pull + ``` + + b. Changing to your local development branch and merging the chamges from the main branch into your local development branch: + ```bash + $ git checkout BRANCH-NAME + $ git merge main + ``` + +At this point, you are fully synchronized with the main CHAP code base, ready for a new cycle of making and submitting changes. + + +Please, check the [Github documentation](https://docs.github.com/en) on [creating your own personal account](https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github), [adding an SSH key to your account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account), [creating an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue), [forking a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo), or [submitting a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) for additional helpful hints. diff --git a/docs/index.rst b/docs/index.rst index dc243a67..ad78c2d2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,12 @@ Chess Analysis Pipeline (CHAP) introduction +.. toctree:: + :titlesonly: + :caption: Contributions + + CONTRIBUTIONS + .. toctree:: :titlesonly: :caption: Installation From a1a5ed31b322dd7d700d010a160762569fb421d6 Mon Sep 17 00:00:00 2001 From: Rolf Verberg Date: Tue, 7 Jul 2026 13:21:13 -0400 Subject: [PATCH 23/23] build: try deploy from doc branch again --- docs/CONTRIBUTIONS.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/CONTRIBUTIONS.md b/docs/CONTRIBUTIONS.md index 3236f8e3..c88551fb 100644 --- a/docs/CONTRIBUTIONS.md +++ b/docs/CONTRIBUTIONS.md @@ -1,8 +1,6 @@ (contributions)= # Contributions -A small change to debug deployment - We welcome feedback, suggestions, issues and bug reports. Feel free to fork the [repository](https://github.com/CHESSComputing/ChessAnalysisPipeline) on GitHub and send a pull request, or to contribute by [submitting an issue](https://github.com/CHESSComputing/ChessAnalysisPipeline/issues). Each contribution helps CHAP grow and improve.