From 751995f330898180d4e12092bbff34bc4233ddbb Mon Sep 17 00:00:00 2001 From: glass-ships Date: Mon, 6 Jan 2025 13:36:28 -0500 Subject: [PATCH 1/3] Migrate to mkdocs --- .github/dependabot.yml | 10 + .github/workflows/actions.yml | 37 ++-- .github/workflows/deploy_docs.yaml | 38 ++++ .pre-commit-config.yaml | 8 +- Makefile | 11 +- docs/Makefile | 195 ------------------ docs/api/background.md | 1 + docs/api/event_reduction.md | 1 + docs/api/index.md | 11 + docs/api/output.md | 1 + docs/api/peak_finding.md | 1 + docs/api/reduction_template_reader.md | 1 + docs/api/template.md | 1 + docs/api/time_resolved.md | 1 + docs/api/utils.md | 1 + docs/api/workflow.md | 1 + docs/conf.py | 74 ------- .../contributing.md} | 9 +- docs/developer/developer.md | 137 ++++++++++++ docs/index.md | 27 +++ docs/index.rst | 42 ---- docs/make.bat | 35 ---- docs/{source/releases.rst => releases.md} | 21 +- docs/source/api/lr_reduction.rst | 81 -------- docs/source/developer/developer.rst | 141 ------------- .../conda_environments.md} | 23 +-- environment.yml | 10 +- mkdocs.yaml | 42 ++++ pyproject.toml | 75 ++++--- 29 files changed, 382 insertions(+), 654 deletions(-) create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/deploy_docs.yaml delete mode 100644 docs/Makefile create mode 100644 docs/api/background.md create mode 100644 docs/api/event_reduction.md create mode 100644 docs/api/index.md create mode 100644 docs/api/output.md create mode 100644 docs/api/peak_finding.md create mode 100644 docs/api/reduction_template_reader.md create mode 100644 docs/api/template.md create mode 100644 docs/api/time_resolved.md create mode 100644 docs/api/utils.md create mode 100644 docs/api/workflow.md delete mode 100644 docs/conf.py rename docs/{source/developer/contributing.rst => developer/contributing.md} (84%) create mode 100644 docs/developer/developer.md create mode 100644 docs/index.md delete mode 100644 docs/index.rst delete mode 100644 docs/make.bat rename docs/{source/releases.rst => releases.md} (80%) delete mode 100644 docs/source/api/lr_reduction.rst delete mode 100644 docs/source/developer/developer.rst rename docs/{source/user/conda_environments.rst => user/conda_environments.md} (73%) create mode 100644 mkdocs.yaml diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..f9c645b --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,10 @@ +# Set update schedule for GitHub Actions + +version: 2 +updates: + + - package-ecosystem: "github-actions" + directory: "/" + schedule: + # Check for updates to GitHub Actions every week + interval: "monthly" \ No newline at end of file diff --git a/.github/workflows/actions.yml b/.github/workflows/actions.yml index 915d89d..4c16b0f 100644 --- a/.github/workflows/actions.yml +++ b/.github/workflows/actions.yml @@ -14,20 +14,23 @@ jobs: run: shell: bash -l {0} steps: - - uses: actions/checkout@v2 - - name: Set up Miniconda - uses: conda-incubator/setup-miniconda@v2 - with: - auto-update-conda: true - miniforge-version: latest - environment-file: environment.yml - - name: Test with pytest - working-directory: ./reduction - run: | - git submodule add --force https://code.ornl.gov/sns-hfir-scse/infrastructure/test-data/liquidsreflectometer-data.git tests/data/liquidsreflectometer-data - git submodule update --init - python -m pytest -vv --cov=. --cov-report=xml --cov-report=term test - - name: Upload coverage reports to Codecov - uses: codecov/codecov-action@v3 - env: - CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} + - uses: actions/checkout@v4 + + - name: Set up Miniconda + uses: conda-incubator/setup-miniconda@v3 + with: + auto-update-conda: true + miniforge-version: latest + environment-file: environment.yml + + - name: Test with pytest + working-directory: ./reduction + run: | + git submodule add --force https://code.ornl.gov/sns-hfir-scse/infrastructure/test-data/liquidsreflectometer-data.git tests/data/liquidsreflectometer-data + git submodule update --init + python -m pytest -vv --cov=. --cov-report=xml --cov-report=term test + + - name: Upload coverage reports to Codecov + uses: codecov/codecov-action@v3 + env: + CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} diff --git a/.github/workflows/deploy_docs.yaml b/.github/workflows/deploy_docs.yaml new file mode 100644 index 0000000..6b6e858 --- /dev/null +++ b/.github/workflows/deploy_docs.yaml @@ -0,0 +1,38 @@ +name: Build and Deploy Docs to GitHub Pages +on: + workflow_dispatch: + push: + branches: + - master + +env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + +jobs: + build-docs: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 # otherwise, you will failed to push refs to dest repo + + - name: Set up Miniconda + uses: conda-incubator/setup-miniconda@v3 + with: + auto-update-conda: true + miniforge-version: latest + environment-file: environment.yml + + - name: Install Dependencies + run: pip install .[dev] + + - name: Build Documentation + run: make docs + + - name: Deploy to gh-pages + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: site + target-folder: docs + clean: true diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1f63629..d542a7a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -4,7 +4,7 @@ exclude: '(reduction/data|reduction/notebooks|scripts|scans)/.*' repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.4.0 + rev: v5.0.0 hooks: - id: check-added-large-files args: [--maxkb=4096] @@ -12,8 +12,12 @@ repos: - id: end-of-file-fixer - id: trailing-whitespace - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.0.278 + rev: v0.8.3 hooks: - id: ruff args: [--fix, --exit-non-zero-on-fix] types_or: [python, pyi, jupyter] + +ci: + autoupdate_schedule: monthly + skip: [eslint] diff --git a/Makefile b/Makefile index 795b416..42710e7 100644 --- a/Makefile +++ b/Makefile @@ -10,12 +10,12 @@ SHELL=/bin/bash .PHONY: help conda docs test install help: - # this nifty perl one-liner collects all commnents headed by the double "#" symbols next to each target and recycles them as comments + # This nifty perl one-liner collects all commnents headed by the double "#" symbols next to each target and recycles them as comments @perl -nle'print $& if m{^[a-zA-Z_-]+:.*?## .*$$}' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-25s\033[0m %s\n", $$1, $$2}' PREFIX := /SNS/REF_L/shared -install: ## install the automated reduction code for LR +install: ## Install the automated reduction code for LR versioningit -w cp -R scripts/livereduce/*.py $(PREFIX)/livereduce cp -R scripts/autoreduce/*.py $(PREFIX)/autoreduce @@ -32,9 +32,8 @@ conda-env: ## creates conda environment `lr_reduction` and installs package `lr $(CONDA_ACTIVATE) lr_reduction pip install -e . -docs: ## generates HTML docs under `docs/_build/html/`, treating warnings as errors. Requires activation of the `lr_reduction` conda environment - # this will fail on a warning - @cd docs&& make html SPHINXOPTS="-W --keep-going -n" && echo -e "##########\n DOCS point your browser to file://$$(pwd)/build/html/index.html\n##########" +docs: ## Build the documentation + mkdocs build -test-all: ## run all tests +test-all: ## Run all tests pytest ./test diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 96fe2a3..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,195 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. - -# Options should be aligned with how the documentation is built on RTD -# (except for '--keep-going', failing fast is prefered on local builds) -# We also remove '-E' to reduce the time of rebuilding reference indexes -# on each build. -SPHINXOPTS = -T -j auto -W -SPHINXBUILD = sphinx-build -PAPER = -PROJECT ?= lr_reduction -BUILDDIR = build - -# Do not use local Django settings during the docs build -export DJANGO_SETTINGS_SKIP_LOCAL = True - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -auto: - sphinx-autobuild --port 8888 $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -livehtml: - sphinx-autobuild --port 4444 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/sdf.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/sdf.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/sdf" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/sdf" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/api/background.md b/docs/api/background.md new file mode 100644 index 0000000..a344220 --- /dev/null +++ b/docs/api/background.md @@ -0,0 +1 @@ +::: lr_reduction.background \ No newline at end of file diff --git a/docs/api/event_reduction.md b/docs/api/event_reduction.md new file mode 100644 index 0000000..ef7f66f --- /dev/null +++ b/docs/api/event_reduction.md @@ -0,0 +1 @@ +::: lr_reduction.event_reduction \ No newline at end of file diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 0000000..a4895cc --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,11 @@ +# Overview + +- [lr_reduction.background](./background.md) +- [lr_reduction.event_reduction](./event_reduction.md) +- [lr_reduction.output](./output.md) +- [lr_reduction.peak_finding](./peak_finding.md) +- [lr_reduction.reduction_template_reader](./reduction_template_reader.md) +- [lr_reduction.template](./template.md) +- [lr_reduction.time_resolved](./time_resolved.md) +- [lr_reduction.utils](./utils.md) +- [lr_reduction.workflow](./workflow.md) diff --git a/docs/api/output.md b/docs/api/output.md new file mode 100644 index 0000000..a49611b --- /dev/null +++ b/docs/api/output.md @@ -0,0 +1 @@ +::: lr_reduction.output \ No newline at end of file diff --git a/docs/api/peak_finding.md b/docs/api/peak_finding.md new file mode 100644 index 0000000..1c14c96 --- /dev/null +++ b/docs/api/peak_finding.md @@ -0,0 +1 @@ +::: lr_reduction.peak_finding \ No newline at end of file diff --git a/docs/api/reduction_template_reader.md b/docs/api/reduction_template_reader.md new file mode 100644 index 0000000..22cf862 --- /dev/null +++ b/docs/api/reduction_template_reader.md @@ -0,0 +1 @@ +::: lr_reduction.reduction_template_reader \ No newline at end of file diff --git a/docs/api/template.md b/docs/api/template.md new file mode 100644 index 0000000..9774ae4 --- /dev/null +++ b/docs/api/template.md @@ -0,0 +1 @@ +::: lr_reduction.template \ No newline at end of file diff --git a/docs/api/time_resolved.md b/docs/api/time_resolved.md new file mode 100644 index 0000000..1a1f1bb --- /dev/null +++ b/docs/api/time_resolved.md @@ -0,0 +1 @@ +::: lr_reduction.time_resolved \ No newline at end of file diff --git a/docs/api/utils.md b/docs/api/utils.md new file mode 100644 index 0000000..89529da --- /dev/null +++ b/docs/api/utils.md @@ -0,0 +1 @@ +::: lr_reduction.utils \ No newline at end of file diff --git a/docs/api/workflow.md b/docs/api/workflow.md new file mode 100644 index 0000000..663c631 --- /dev/null +++ b/docs/api/workflow.md @@ -0,0 +1 @@ +::: lr_reduction.workflow \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 6dc63c6..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,74 +0,0 @@ -"""Configuration file for the Sphinx documentation builder. -For the full list of built-in configuration values, see the documentation: -https://www.sphinx-doc.org/en/master/usage/configuration.html -""" -import os -import sys -import versioningit - -sys.path.insert(0, os.path.abspath("../reduction")) - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "lr_reduction" -copyright = "2024, ORNL" # noqa A001 -author = "ORNL" -version = versioningit.get_version("../") -# The full version, including alpha/beta/rc tags -release = "source/".join(version.split("source/")[:-1]) - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - "sphinx.ext.duration", - "sphinx.ext.doctest", - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", - "sphinx.ext.intersphinx", - "sphinx.ext.viewcode", - "sphinx.ext.coverage", -] - -autodoc_mock_imports = [ - "mantid", - "mantid.api", - "mantid.kernel", - "mantid.utils", - "mantid.utils.logging", - "mantid.simpleapi", - "mantid.geometry", - "mantidqt.widgets", - "mantidqt.widgets.algorithmprogress", - "qtpy", - "qtpy.uic", - "qtpy.QtWidgets", - "mantidqt", - "mantid.plots", - "mantid.plots.plotfunctions", - "mantid.plots.datafunctions", - "mantid.plots.utility", -] - -master_doc = "index" - -intersphinx_mapping = { - "python": ("https://docs.python.org/3/", None), - "sphinx": ("https://www.sphinx-doc.org/en/master/", None), -} -intersphinx_disabled_domains = ["std"] - -templates_path = ["_templates"] -exclude_patterns = ["_build"] -pygments_style = "sphinx" - - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = "sphinx_rtd_theme" # pylint: disable=C0103 - -html_theme_options = {"style_nav_header_background": "#472375"} - -epub_show_urls = "footnote" # pylint: disable=C0103 diff --git a/docs/source/developer/contributing.rst b/docs/developer/contributing.md similarity index 84% rename from docs/source/developer/contributing.rst rename to docs/developer/contributing.md index 847e838..8bcb5f9 100644 --- a/docs/source/developer/contributing.rst +++ b/docs/developer/contributing.md @@ -1,7 +1,4 @@ -.. contributing - -Guide to Contributing -===================== +# Contributing Guide Contributions to this project are welcome. All contributors agree to the following: @@ -13,7 +10,7 @@ Contributions to this project are welcome. All contributors agree to the followi All contributions must be "signed off" in the commit log and by doing so you agree to the above. -Getting access to the main project ----------------------------------- +## Getting access to the main project + Direct commit access to the project is currently restricted to core developers. All other contributions should be done through pull requests. diff --git a/docs/developer/developer.md b/docs/developer/developer.md new file mode 100644 index 0000000..61e76fb --- /dev/null +++ b/docs/developer/developer.md @@ -0,0 +1,137 @@ +# Developer Documentation + +- [Local Environment](#local-environment) +- [pre-commit Hooks](#pre-commit-hooks) +- [Development procedure](#development-procedure) +- [Updating mantid dependency](#updating-mantid-dependency) +- [Using the Data Repository](#using-the-data-repository) +- [Coverage reports](#coverage-reports) +- [Building the documentation](#building-the-documentation) +- [Creating a stable release](#creating-a-stable-release) + +## Local Environment + +For purposes of development, create conda environment `lr_reduction` with file `environment.yml`, and then +install the package in development mode with `pip`: + +```bash +$ cd /path/to/lr_reduction/ +$ conda create env --solver libmamba --file ./environment.yml +$ conda activate lr_reduction +(lr_reduction)$ pip install -e ./ +``` + +By installing the package in development mode, one doesn't need to re-install package `lr_reduction` in conda +environment `lr_reduction` after every change to the source code. + +## pre-commit Hooks + +Activate the hooks by typing in the terminal: + +```bash +$ cd /path/to/mr_reduction/ +$ conda activate mr_reduction +(mr_reduction)$ pre-commit install +``` + +## Development procedure + +1. A developer is assigned with a task during neutron status meeting and changes the task's status to **In Progress**. +2. The developer creates a branch off _next_ and completes the task in this branch. +3. The developer creates a pull request (PR) off _next_. +4. Any new features or bugfixes must be covered by new and/or refactored automated tests. +5. The developer asks for another developer as a reviewer to review the PR. + A PR can only be approved and merged by the reviewer. +6. The developer changes the task’s status to **Complete** and closes the associated issue. + +## Updating mantid dependency + +The mantid version and the mantid conda channel (`mantid/label/main` or `mantid/label/nightly`) **must** be +synchronized across these files: + +- environment.yml +- conda.recipe/meta.yml +- .github/workflows/package.yml + +## Using the Data Repository + +To run the integration tests in your local environment, it is necessary first to download the data files. +Because of their size, the files are stored in the Git LFS repository +`lr_reduction-data `\_. + +It is necessary to have package `git-lfs` installed in your machine. + +```bash +$ sudo apt install git-lfs +``` + +After this step, initialize or update the data repository: + +```bash +$ cd /path/to/lr_reduction +$ git submodule update --init +``` + +This will either clone `liquidsreflectometer-data` into `/path/to/lr_reduction/tests/liquidsreflectometer-data` or +bring the `liquidsreflectometer-data`'s refspec in sync with the refspec listed within file +`/path/to/liquidsreflectometer/.gitmodules`. + +An intro to Git LFS in the context of the Neutron Data Project is found in the +`Confluence pages `\_ +(login required). + +## Coverage reports + +GitHuh actions create reports for unit and integration tests, then combine into one report and upload it to +`Codecov `\_. + +## Building the documentation + +A repository webhook is setup to automatically trigger the latest documentation build by GitHub actions. +To manually build the documentation: + +```bash +$ conda activate lr_reduction +(lr_reduction)$ make docs +``` + +After this, point your browser to +`file:///path/to/lr_reduction/docs/build/html/index.html` + +## Creating a stable release + +- _patch_ release, it may be allowed to bypass the creation of a candidate release. + Still, we must update branch `qa` first, then create the release tag in branch `main`. + For instance, to create patch version "v2.1.1": + +```bash +VERSION="v2.1.2" + +# update the local repository +git fetch --all --prune +git fetch --prune --prune-tags origin + +# update branch qa from next, possibly bringing work done in qa missing in next +git switch next +git rebase -v origin/next +git merge --no-edit origin/qa # commit message is automatically generated +git push origin next # required to "link" qa to next, for future fast-forward +git switch qa +git rebase -v origin/qa +git merge --ff-only origin/next + +# update branch main from qa +git merge --no-edit origin/main # commit message is automatically generated +git push origin qa # required to "link" main to qa, for future fast-forward +git switch main +git rebase -v origin/main +git merge --ff-only origin/qa +git tag $VERSION +git push origin --tags main +``` + +- _minor_ or _major_ release, we create a stable release _after_ we have created a Candidate release. + For this customary procedure, follow: + - The [Software Maturity Model](https://ornl-neutrons.atlassian.net/wiki/spaces/NDPD/pages/23363585/Software+Maturity+Model) for continous versioning as well as creating release candidates and stable releases. + + - Update the :ref:`Release Notes ` with major fixes, updates and additions since last stable release. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e4e4466 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,27 @@ +# Liquids Reflectometer Reduction + +## User Guide + +- [Conda Environments](./user/conda_environments.md) +- [Releases](./releases.md) + + +### Contacting the Team + +The best mechanism for a user to request a change or report a bug is to contact the SANS CIS. +Please email [Mathieu Doucet](mailto:doucetm@ornl.gov) with your request. + +A change needs to be in the form of a: + +- Story for any enhancement request +- Defect for any bug fix request. + +## API + +- [lr_reduction](source/api/lr_reduction.md) + + +## Developer Guide + +- [Contributing Guide](source/developer/contributing.md) +- [Developer Documentation](source/developer/developer.md) diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 2447dcf..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. :lr_reduction: - -Welcome to lr_reduction (Liquids Reflectometer Reduction) documentation -======================================================================= - -User Guide ----------- - -.. toctree:: - :titlesonly: - - /source/user/conda_environments - /source/releases - -Contacting the Team -+++++++++++++++++++ -The best mechanism for a user to request a change or report a bug is to contact the SANS CIS. -Please email `Mathieu Doucet`_ with your request. - -.. _Mathieu Doucet: doucetm@ornl.gov - -A change needs to be in the form of a: - -- Story for any enhancement request -- Defect for any bug fix request. - -API ---- - -.. toctree:: - :titlesonly: - - /source/api/lr_reduction - -Developer Guide ---------------- - -.. toctree:: - :titlesonly: - - /source/developer/contributing - /source/developer/developer diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 9534b01..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/releases.rst b/docs/releases.md similarity index 80% rename from docs/source/releases.rst rename to docs/releases.md index 47b3161..6f75297 100644 --- a/docs/source/releases.rst +++ b/docs/releases.md @@ -1,11 +1,13 @@ -.. _release_notes: +# Release Notes -Release Notes -============= -Notes for major or minor releases. Notes for patch releases are deferred +Notes for major or minor releases. Notes for patch releases are deferred. + +Release notes are written in reverse chronological order, with the most recent release at the top, +using the following format: + +```markdown +## - ------------------------------ (date of release, format YYYY-MM-DD) **Of interest to the User**: @@ -14,10 +16,10 @@ Notes for major or minor releases. Notes for patch releases are deferred **Of interest to the Developer:** -- PR #40 documentation to create a patch release +- PR #XYZ one-liner description +``` -2.1.0 ------ +## 2.1.0 **Of interest to the User**: @@ -29,6 +31,7 @@ Notes for major or minor releases. Notes for patch releases are deferred **Of interest to the Developer:** +- PR #40 documentation to create a patch release - PR #37 documentation conforming to that of the python project template - PR #36 versioning with versioningit - PR #25 Read in error events when computing correction diff --git a/docs/source/api/lr_reduction.rst b/docs/source/api/lr_reduction.rst deleted file mode 100644 index 213ae65..0000000 --- a/docs/source/api/lr_reduction.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. api_lr_reduction: - -lr_reduction package -==================== - -.. contents:: - :local: - :depth: 1 - -lr_reduction.background ------------------------ - -.. automodule:: lr_reduction.background - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.event_reduction ----------------------------- - -.. automodule:: lr_reduction.event_reduction - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.output -------------------- - -.. automodule:: lr_reduction.output - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.peak_finding -------------------------- - -.. automodule:: lr_reduction.peak_finding - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.reduction_template_reader --------------------------------------- - -.. automodule:: lr_reduction.reduction_template_reader - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.template ---------------------- - -.. automodule:: lr_reduction.template - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.time_resolved --------------------------- - -.. automodule:: lr_reduction.time_resolved - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.utils ------------------- - -.. automodule:: lr_reduction.utils - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.workflow ---------------------- - -.. automodule:: lr_reduction.workflow - :members: - :undoc-members: - :show-inheritance: - diff --git a/docs/source/developer/developer.rst b/docs/source/developer/developer.rst deleted file mode 100644 index 39e026b..0000000 --- a/docs/source/developer/developer.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. _developer_documentation: - -Developer Documentation -======================= - -.. contents:: - :local: - :depth: 1 - -Local Environment ------------------ -For purposes of development, create conda environment `lr_reduction` with file `environment.yml`, and then -install the package in development mode with `pip`: - -.. code-block:: bash - - $> cd /path/to/lr_reduction/ - $> conda create env --solver libmamba --file ./environment.yml - $> conda activate lr_reduction - (lr_reduction)$> pip install -e ./ - -By installing the package in development mode, one doesn't need to re-install package `lr_reduction` in conda -environment `lr_reduction` after every change to the source code. - -pre-commit Hooks ----------------- - -Activate the hooks by typing in the terminal: - -.. code-block:: bash - - $> cd cd /path/to/mr_reduction/ - $> conda activate mr_reduction - (mr_reduction)$> pre-commit install - -Development procedure ---------------------- - -1. A developer is assigned with a task during neutron status meeting and changes the task's status to **In Progress**. -2. The developer creates a branch off *next* and completes the task in this branch. -3. The developer creates a pull request (PR) off *next*. -4. Any new features or bugfixes must be covered by new and/or refactored automated tests. -5. The developer asks for another developer as a reviewer to review the PR. - A PR can only be approved and merged by the reviewer. -6. The developer changes the task’s status to **Complete** and closes the associated issue. - -Updating mantid dependency --------------------------- -The mantid version and the mantid conda channel (`mantid/label/main` or `mantid/label/nightly`) **must** be -synchronized across these files: - -- environment.yml -- conda.recipe/meta.yml -- .github/workflows/package.yml - -Using the Data Repository liquidsreflectometer-data ---------------------------------------------------- -To run the integration tests in your local environment, it is necessary first to download the data files. -Because of their size, the files are stored in the Git LFS repository -`lr_reduction-data `_. - -It is necessary to have package `git-lfs` installed in your machine. - -.. code-block:: bash - - $> sudo apt install git-lfs - -After this step, initialize or update the data repository: - -.. code-block:: bash - - $> cd /path/to/lr_reduction - $> git submodule update --init - -This will either clone `liquidsreflectometer-data` into `/path/to/lr_reduction/tests/liquidsreflectometer-data` or -bring the `liquidsreflectometer-data`'s refspec in sync with the refspec listed within file -`/path/to/liquidsreflectometer/.gitmodules`. - -An intro to Git LFS in the context of the Neutron Data Project is found in the -`Confluence pages `_ -(login required). - - -Coverage reports ----------------- - -GitHuh actions create reports for unit and integration tests, then combine into one report and upload it to -`Codecov `_. - - -Building the documentation --------------------------- -A repository webhook is setup to automatically trigger the latest documentation build by GitHub actions. -To manually build the documentation: - -.. code-block:: bash - - $> conda activate lr_reduction - (lr_reduction)$> make docs - -After this, point your browser to -`file:///path/to/lr_reduction/docs/build/html/index.html` - - -Creating a stable release -------------------------- - -- *patch* release, it may be allowed to bypass the creation of a candidate release. - Still, we must update branch `qa` first, then create the release tag in branch `main`. - For instance, to create patch version "v2.1.1": - -.. code-block:: bash - - VERSION="v2.1.2" - # update the local repository - git fetch --all --prune - git fetch --prune --prune-tags origin - # update branch qa from next, possibly bringing work done in qa missing in next - git switch next - git rebase -v origin/next - git merge --no-edit origin/qa # commit message is automatically generated - git push origin next # required to "link" qa to next, for future fast-forward - git switch qa - git rebase -v origin/qa - git merge --ff-only origin/next - # update branch main from qa - git merge --no-edit origin/main # commit message is automatically generated - git push origin qa # required to "link" main to qa, for future fast-forward - git switch main - git rebase -v origin/main - git merge --ff-only origin/qa - git tag $VERSION - git push origin --tags main - -- *minor* or *major* release, we create a stable release *after* we have created a Candidate release. - For this customary procedure, follow: - - + the `Software Maturity Model `_ for continous versioning as well as creating release candidates and stable releases. - + Update the :ref:`Release Notes ` with major fixes, updates and additions since last stable release. - - diff --git a/docs/source/user/conda_environments.rst b/docs/user/conda_environments.md similarity index 73% rename from docs/source/user/conda_environments.rst rename to docs/user/conda_environments.md index 7f2ec71..ee418c3 100644 --- a/docs/source/user/conda_environments.rst +++ b/docs/user/conda_environments.md @@ -1,29 +1,26 @@ -.. conda_environments - -Conda Environments -================== +# Conda Environments Three conda environments are available in the analysis nodes, beamline machines, as well as the jupyter notebook severs. On a terminal: -.. code-block:: bash - - $> conda activate +```bash +$ conda activate +``` where `` is one of `lr_reduction`, `lr_reduction-qa`, and `lr_reduction-dev` -lr_reduction Environment ------------------------- +## lr_reduction Environment + Activates the latest stable release of `lr_reduction`. Typically users will reduce their data in this environment. -lr_reduction-qa Environment ---------------------------- +## lr_reduction-qa Environment + Activates a release-candidate environment. Instrument scientists and computational instrument scientists will carry out testing on this environment to prevent bugs being introduce in the next stable release. -lr_reduction-dev Environment ----------------------------- +## lr_reduction-dev Environment + Activates the environment corresponding to the latest changes in the source code. Instrument scientists and computational instrument scientists will test the latest changes to `lr_reduction` in this environment. diff --git a/environment.yml b/environment.yml index 482147e..69958c3 100644 --- a/environment.yml +++ b/environment.yml @@ -7,15 +7,19 @@ dependencies: - lmfit - mantid=6.10 - matplotlib -# development dependencies + # development dependencies - boa - codecov - conda-build - conda-verify + - mkdocs + - mkdocstrings + - mkdocstrings-python - pre-commit - pytest - pytest-cov - python-build - - sphinx - - sphinx-rtd-theme + - ruff + # - sphinx + # - sphinx-rtd-theme - versioningit diff --git a/mkdocs.yaml b/mkdocs.yaml new file mode 100644 index 0000000..f87f8d4 --- /dev/null +++ b/mkdocs.yaml @@ -0,0 +1,42 @@ +site_name: "Liquids Reflectometer" +repo_name: "LiquidsReflectometer" +repo_url: "https://github.com/neutrons/LiquidsReflectometer" + +theme: + name: "readthedocs" + docs_dir: docs/ + # logo: "" + +plugins: + - search + - mkdocstrings: + handlers: + python: + paths: [reduction/lr_reduction] + import: + - https://docs.python.org/3/objects.inv + - https://mkdocstrings.github.io/objects.inv + - https://mkdocstrings.github.io/griffe/objects.inv + options: + # See: https://mkdocstrings.github.io/usage/handlers/?h=docstring_style#selection-options + docstring_style: google + docstring_options: + docstring_section_style: table + ignore_init_summary: yes + merge_init_into_class: yes + # separate_signature: yes + show_signature: no + show_source: no + show_root_full_path: no + show_root_toc_entry: False + filters: + - "!^_[^_]" + # - '^_[^_]' + +extra: + social: + - icon: "fontawesome/solid/house" + link: "https://neutrons.ornl.gov" + - icon: "fontawesome/brands/github-alt" + link: "https://github.com/neutrons/LiquidsReflectometer" +# copyright: "Copyright © 2020 - 2023 [Glass](glass-ships.com)" diff --git a/pyproject.toml b/pyproject.toml index c7587ac..15462c1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,38 +1,27 @@ [project] name = "lr_reduction" -authors = [{name = "Mat", email = "m2d@ornl.gov"}] +authors = [{ name = "Mat", email = "m2d@ornl.gov" }] description = "Reduction scripts for the Liquids Reflectometer. This includes both automated reduction scripts and useful scripts to reprocess data." -version = "0.0.1" # initial version, dynamically overriden -license = {file = "LICENSE"} +version = "0.0.1" # initial version, dynamically overriden +license = { file = "LICENSE" } readme = "README.md" requires-python = ">=3.8" classifiers = [ "Operating System :: OS Independent", "Programming Language :: Python :: 3", - "Topic :: Scientific/Engineering :: Neutron reflectometry" -] -dependencies = [ - "lmfit", - "numpy", - "matplotlib", - "mantid" + "Topic :: Scientific/Engineering :: Neutron reflectometry", ] +dependencies = ["lmfit", "mantid", "matplotlib", "numpy"] + +[project.optional-dependencies] +dev = ["mkdocs", "mkdocstrings[python]", "ruff"] +tests = ["pytest"] # versioningit will generate file _version.py when installing this package, even if installing from sources [build-system] -requires = [ - "setuptools >= 40.6.0", - "wheel", - "toml", - "versioningit" -] +requires = ["setuptools >= 40.6.0", "wheel", "toml", "versioningit"] build-backend = "setuptools.build_meta" -[project.optional-dependencies] -tests = [ - "pytest" -] - [project.urls] Homepage = "https://github.com/neutrons/LiquidsReflectometer" @@ -47,11 +36,13 @@ exclude = ["tests*", "scripts*", "docs*", "notebooks*"] line-length = 140 select = ["A", "ARG", "E", "W", "F", "I", "PT", "RUF100"] ignore = [ - "E402", # module level import not at top of file - "E722", # bare except - "E741", "E743", # ambiguous function name, generally 'l' - "F403", # wild imports - "F405", "F821" # unknown names from probably from wild imports + "E402", # module level import not at top of file + "E722", # bare except + "E741", + "E743", # ambiguous function name, generally 'l' + "F403", # wild imports + "F405", + "F821", # unknown names from probably from wild imports ] [tool.versioningit.vcs] @@ -77,10 +68,20 @@ skip_empty = true [tool.pytest.ini_options] pythonpath = [ - ".", "reduction", "scripts", "tests/data/liquidsreflectometer-data/nexus/" + ".", + "reduction", + "scripts", + "tests/data/liquidsreflectometer-data/nexus/", ] testpaths = ["tests"] -norecursedirs = [".git", "tmp*", "_tmp*", "__pycache__", "*dataset*", "*data_set*"] +norecursedirs = [ + ".git", + "tmp*", + "_tmp*", + "__pycache__", + "*dataset*", + "*data_set*", +] markers = [ "datarepo: mark a test as using LiquidsReflectometer-data repository", "scripts: mark a test as a script that should be run manually", @@ -88,8 +89,22 @@ markers = [ [tool.flake8] ignore = [ - "E114", "E115", "E116", "E121", "E123", "E126", "E133", - "E2", "E704", "E722", "E741", "E743", "W503", "F403", "F405", "F999" + "E114", + "E115", + "E116", + "E121", + "E123", + "E126", + "E133", + "E2", + "E704", + "E722", + "E741", + "E743", + "W503", + "F403", + "F405", + "F999", ] doctests = false max-line-length = 130 From 2ed393eac8fa024c750deb3d2633a30414c1cf17 Mon Sep 17 00:00:00 2001 From: glass-ships Date: Mon, 6 Jan 2025 13:44:25 -0500 Subject: [PATCH 2/3] ruff non source code files --- .github/dependabot.yml | 2 +- .github/pull_request_template.md | 1 - docs-sphinx/Makefile | 195 ++++++++++++++++++ docs-sphinx/conf.py | 74 +++++++ docs-sphinx/index.rst | 42 ++++ docs-sphinx/make.bat | 35 ++++ docs-sphinx/source/api/lr_reduction.rst | 81 ++++++++ docs-sphinx/source/developer/contributing.rst | 19 ++ docs-sphinx/source/developer/developer.rst | 141 +++++++++++++ docs-sphinx/source/releases.rst | 38 ++++ .../source/user/conda_environments.rst | 29 +++ docs/api/background.md | 2 +- docs/api/event_reduction.md | 2 +- docs/api/output.md | 2 +- docs/api/peak_finding.md | 2 +- docs/api/reduction_template_reader.md | 2 +- docs/api/template.md | 2 +- docs/api/time_resolved.md | 2 +- docs/api/utils.md | 2 +- docs/api/workflow.md | 2 +- docs/developer/developer.md | 3 +- docs/index.md | 5 +- docs/releases.md | 2 +- reduction/lr_reduction/DeadTimeCorrection.py | 8 +- reduction/lr_reduction/__init__.py | 2 +- reduction/lr_reduction/event_reduction.py | 2 +- .../scaling_factors/LRDirectBeamSort.py | 13 +- .../scaling_factors/LRScalingFactors.py | 3 +- reduction/test/test_dead_time.py | 41 ++-- reduction/test/test_scaling_factors.py | 11 +- 30 files changed, 707 insertions(+), 58 deletions(-) create mode 100644 docs-sphinx/Makefile create mode 100644 docs-sphinx/conf.py create mode 100644 docs-sphinx/index.rst create mode 100644 docs-sphinx/make.bat create mode 100644 docs-sphinx/source/api/lr_reduction.rst create mode 100644 docs-sphinx/source/developer/contributing.rst create mode 100644 docs-sphinx/source/developer/developer.rst create mode 100644 docs-sphinx/source/releases.rst create mode 100644 docs-sphinx/source/user/conda_environments.rst diff --git a/.github/dependabot.yml b/.github/dependabot.yml index f9c645b..674f488 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -7,4 +7,4 @@ updates: directory: "/" schedule: # Check for updates to GitHub Actions every week - interval: "monthly" \ No newline at end of file + interval: "monthly" diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 526a52a..622e81d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -23,4 +23,3 @@ Check all that apply: - [ ] All the tests are passing - [ ] The documentation is up to date - [ ] code comments added when explaining intent - diff --git a/docs-sphinx/Makefile b/docs-sphinx/Makefile new file mode 100644 index 0000000..96fe2a3 --- /dev/null +++ b/docs-sphinx/Makefile @@ -0,0 +1,195 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. + +# Options should be aligned with how the documentation is built on RTD +# (except for '--keep-going', failing fast is prefered on local builds) +# We also remove '-E' to reduce the time of rebuilding reference indexes +# on each build. +SPHINXOPTS = -T -j auto -W +SPHINXBUILD = sphinx-build +PAPER = +PROJECT ?= lr_reduction +BUILDDIR = build + +# Do not use local Django settings during the docs build +export DJANGO_SETTINGS_SKIP_LOCAL = True + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +auto: + sphinx-autobuild --port 8888 $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +livehtml: + sphinx-autobuild --port 4444 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/sdf.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/sdf.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/sdf" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/sdf" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs-sphinx/conf.py b/docs-sphinx/conf.py new file mode 100644 index 0000000..6dc63c6 --- /dev/null +++ b/docs-sphinx/conf.py @@ -0,0 +1,74 @@ +"""Configuration file for the Sphinx documentation builder. +For the full list of built-in configuration values, see the documentation: +https://www.sphinx-doc.org/en/master/usage/configuration.html +""" +import os +import sys +import versioningit + +sys.path.insert(0, os.path.abspath("../reduction")) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "lr_reduction" +copyright = "2024, ORNL" # noqa A001 +author = "ORNL" +version = versioningit.get_version("../") +# The full version, including alpha/beta/rc tags +release = "source/".join(version.split("source/")[:-1]) + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.duration", + "sphinx.ext.doctest", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinx.ext.coverage", +] + +autodoc_mock_imports = [ + "mantid", + "mantid.api", + "mantid.kernel", + "mantid.utils", + "mantid.utils.logging", + "mantid.simpleapi", + "mantid.geometry", + "mantidqt.widgets", + "mantidqt.widgets.algorithmprogress", + "qtpy", + "qtpy.uic", + "qtpy.QtWidgets", + "mantidqt", + "mantid.plots", + "mantid.plots.plotfunctions", + "mantid.plots.datafunctions", + "mantid.plots.utility", +] + +master_doc = "index" + +intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + "sphinx": ("https://www.sphinx-doc.org/en/master/", None), +} +intersphinx_disabled_domains = ["std"] + +templates_path = ["_templates"] +exclude_patterns = ["_build"] +pygments_style = "sphinx" + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" # pylint: disable=C0103 + +html_theme_options = {"style_nav_header_background": "#472375"} + +epub_show_urls = "footnote" # pylint: disable=C0103 diff --git a/docs-sphinx/index.rst b/docs-sphinx/index.rst new file mode 100644 index 0000000..2447dcf --- /dev/null +++ b/docs-sphinx/index.rst @@ -0,0 +1,42 @@ +.. :lr_reduction: + +Welcome to lr_reduction (Liquids Reflectometer Reduction) documentation +======================================================================= + +User Guide +---------- + +.. toctree:: + :titlesonly: + + /source/user/conda_environments + /source/releases + +Contacting the Team ++++++++++++++++++++ +The best mechanism for a user to request a change or report a bug is to contact the SANS CIS. +Please email `Mathieu Doucet`_ with your request. + +.. _Mathieu Doucet: doucetm@ornl.gov + +A change needs to be in the form of a: + +- Story for any enhancement request +- Defect for any bug fix request. + +API +--- + +.. toctree:: + :titlesonly: + + /source/api/lr_reduction + +Developer Guide +--------------- + +.. toctree:: + :titlesonly: + + /source/developer/contributing + /source/developer/developer diff --git a/docs-sphinx/make.bat b/docs-sphinx/make.bat new file mode 100644 index 0000000..9534b01 --- /dev/null +++ b/docs-sphinx/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs-sphinx/source/api/lr_reduction.rst b/docs-sphinx/source/api/lr_reduction.rst new file mode 100644 index 0000000..213ae65 --- /dev/null +++ b/docs-sphinx/source/api/lr_reduction.rst @@ -0,0 +1,81 @@ +.. api_lr_reduction: + +lr_reduction package +==================== + +.. contents:: + :local: + :depth: 1 + +lr_reduction.background +----------------------- + +.. automodule:: lr_reduction.background + :members: + :undoc-members: + :show-inheritance: + +lr_reduction.event_reduction +---------------------------- + +.. automodule:: lr_reduction.event_reduction + :members: + :undoc-members: + :show-inheritance: + +lr_reduction.output +------------------- + +.. automodule:: lr_reduction.output + :members: + :undoc-members: + :show-inheritance: + +lr_reduction.peak_finding +------------------------- + +.. automodule:: lr_reduction.peak_finding + :members: + :undoc-members: + :show-inheritance: + +lr_reduction.reduction_template_reader +-------------------------------------- + +.. automodule:: lr_reduction.reduction_template_reader + :members: + :undoc-members: + :show-inheritance: + +lr_reduction.template +--------------------- + +.. automodule:: lr_reduction.template + :members: + :undoc-members: + :show-inheritance: + +lr_reduction.time_resolved +-------------------------- + +.. automodule:: lr_reduction.time_resolved + :members: + :undoc-members: + :show-inheritance: + +lr_reduction.utils +------------------ + +.. automodule:: lr_reduction.utils + :members: + :undoc-members: + :show-inheritance: + +lr_reduction.workflow +--------------------- + +.. automodule:: lr_reduction.workflow + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs-sphinx/source/developer/contributing.rst b/docs-sphinx/source/developer/contributing.rst new file mode 100644 index 0000000..847e838 --- /dev/null +++ b/docs-sphinx/source/developer/contributing.rst @@ -0,0 +1,19 @@ +.. contributing + +Guide to Contributing +===================== + +Contributions to this project are welcome. All contributors agree to the following: + +- It is assumed that the contributor is an ORNL employee and belongs to the development team. + Thus the following instructions are specific to ORNL development team's process. +- You have permission and any required rights to submit your contribution. +- Your contribution is provided under the license of this project and may be redistributed as such. +- All contributions to this project are public. + +All contributions must be "signed off" in the commit log and by doing so you agree to the above. + +Getting access to the main project +---------------------------------- +Direct commit access to the project is currently restricted to core developers. +All other contributions should be done through pull requests. diff --git a/docs-sphinx/source/developer/developer.rst b/docs-sphinx/source/developer/developer.rst new file mode 100644 index 0000000..39e026b --- /dev/null +++ b/docs-sphinx/source/developer/developer.rst @@ -0,0 +1,141 @@ +.. _developer_documentation: + +Developer Documentation +======================= + +.. contents:: + :local: + :depth: 1 + +Local Environment +----------------- +For purposes of development, create conda environment `lr_reduction` with file `environment.yml`, and then +install the package in development mode with `pip`: + +.. code-block:: bash + + $> cd /path/to/lr_reduction/ + $> conda create env --solver libmamba --file ./environment.yml + $> conda activate lr_reduction + (lr_reduction)$> pip install -e ./ + +By installing the package in development mode, one doesn't need to re-install package `lr_reduction` in conda +environment `lr_reduction` after every change to the source code. + +pre-commit Hooks +---------------- + +Activate the hooks by typing in the terminal: + +.. code-block:: bash + + $> cd cd /path/to/mr_reduction/ + $> conda activate mr_reduction + (mr_reduction)$> pre-commit install + +Development procedure +--------------------- + +1. A developer is assigned with a task during neutron status meeting and changes the task's status to **In Progress**. +2. The developer creates a branch off *next* and completes the task in this branch. +3. The developer creates a pull request (PR) off *next*. +4. Any new features or bugfixes must be covered by new and/or refactored automated tests. +5. The developer asks for another developer as a reviewer to review the PR. + A PR can only be approved and merged by the reviewer. +6. The developer changes the task’s status to **Complete** and closes the associated issue. + +Updating mantid dependency +-------------------------- +The mantid version and the mantid conda channel (`mantid/label/main` or `mantid/label/nightly`) **must** be +synchronized across these files: + +- environment.yml +- conda.recipe/meta.yml +- .github/workflows/package.yml + +Using the Data Repository liquidsreflectometer-data +--------------------------------------------------- +To run the integration tests in your local environment, it is necessary first to download the data files. +Because of their size, the files are stored in the Git LFS repository +`lr_reduction-data `_. + +It is necessary to have package `git-lfs` installed in your machine. + +.. code-block:: bash + + $> sudo apt install git-lfs + +After this step, initialize or update the data repository: + +.. code-block:: bash + + $> cd /path/to/lr_reduction + $> git submodule update --init + +This will either clone `liquidsreflectometer-data` into `/path/to/lr_reduction/tests/liquidsreflectometer-data` or +bring the `liquidsreflectometer-data`'s refspec in sync with the refspec listed within file +`/path/to/liquidsreflectometer/.gitmodules`. + +An intro to Git LFS in the context of the Neutron Data Project is found in the +`Confluence pages `_ +(login required). + + +Coverage reports +---------------- + +GitHuh actions create reports for unit and integration tests, then combine into one report and upload it to +`Codecov `_. + + +Building the documentation +-------------------------- +A repository webhook is setup to automatically trigger the latest documentation build by GitHub actions. +To manually build the documentation: + +.. code-block:: bash + + $> conda activate lr_reduction + (lr_reduction)$> make docs + +After this, point your browser to +`file:///path/to/lr_reduction/docs/build/html/index.html` + + +Creating a stable release +------------------------- + +- *patch* release, it may be allowed to bypass the creation of a candidate release. + Still, we must update branch `qa` first, then create the release tag in branch `main`. + For instance, to create patch version "v2.1.1": + +.. code-block:: bash + + VERSION="v2.1.2" + # update the local repository + git fetch --all --prune + git fetch --prune --prune-tags origin + # update branch qa from next, possibly bringing work done in qa missing in next + git switch next + git rebase -v origin/next + git merge --no-edit origin/qa # commit message is automatically generated + git push origin next # required to "link" qa to next, for future fast-forward + git switch qa + git rebase -v origin/qa + git merge --ff-only origin/next + # update branch main from qa + git merge --no-edit origin/main # commit message is automatically generated + git push origin qa # required to "link" main to qa, for future fast-forward + git switch main + git rebase -v origin/main + git merge --ff-only origin/qa + git tag $VERSION + git push origin --tags main + +- *minor* or *major* release, we create a stable release *after* we have created a Candidate release. + For this customary procedure, follow: + + + the `Software Maturity Model `_ for continous versioning as well as creating release candidates and stable releases. + + Update the :ref:`Release Notes ` with major fixes, updates and additions since last stable release. + + diff --git a/docs-sphinx/source/releases.rst b/docs-sphinx/source/releases.rst new file mode 100644 index 0000000..47b3161 --- /dev/null +++ b/docs-sphinx/source/releases.rst @@ -0,0 +1,38 @@ +.. _release_notes: + +Release Notes +============= +Notes for major or minor releases. Notes for patch releases are deferred + + +----------------------------- +(date of release, format YYYY-MM-DD) + +**Of interest to the User**: + +- PR #XYZ one-liner description + +**Of interest to the Developer:** + +- PR #40 documentation to create a patch release + +2.1.0 +----- + +**Of interest to the User**: + +- PR #33 enable dead time correction for runs with skipped pulses +- PR #26 add dead time correction to the computation of scaling factors +- PR #23 add dead time correction +- PR #19 Functionality to use two backgrounds +- PR #15 Ability to fit a background with a polynomial function + +**Of interest to the Developer:** + +- PR #37 documentation conforming to that of the python project template +- PR #36 versioning with versioningit +- PR #25 Read in error events when computing correction +- PR #21 switch dependency from mantidworkbench to mantid +- PR #20 allow runtime initialization of new attributes for ReductionParameters +- PR #14 add first GitHub actions +- PR #12 switch from mantid to mantidworkbench conda package diff --git a/docs-sphinx/source/user/conda_environments.rst b/docs-sphinx/source/user/conda_environments.rst new file mode 100644 index 0000000..7f2ec71 --- /dev/null +++ b/docs-sphinx/source/user/conda_environments.rst @@ -0,0 +1,29 @@ +.. conda_environments + +Conda Environments +================== + +Three conda environments are available in the analysis nodes, beamline machines, as well as the +jupyter notebook severs. On a terminal: + +.. code-block:: bash + + $> conda activate + +where `` is one of `lr_reduction`, `lr_reduction-qa`, and `lr_reduction-dev` + +lr_reduction Environment +------------------------ +Activates the latest stable release of `lr_reduction`. Typically users will reduce their data in this environment. + +lr_reduction-qa Environment +--------------------------- +Activates a release-candidate environment. +Instrument scientists and computational instrument scientists will carry out testing on this environment +to prevent bugs being introduce in the next stable release. + +lr_reduction-dev Environment +---------------------------- +Activates the environment corresponding to the latest changes in the source code. +Instrument scientists and computational instrument scientists will test the latest changes to `lr_reduction` in this +environment. diff --git a/docs/api/background.md b/docs/api/background.md index a344220..5e54a78 100644 --- a/docs/api/background.md +++ b/docs/api/background.md @@ -1 +1 @@ -::: lr_reduction.background \ No newline at end of file +::: lr_reduction.background diff --git a/docs/api/event_reduction.md b/docs/api/event_reduction.md index ef7f66f..9cdbec8 100644 --- a/docs/api/event_reduction.md +++ b/docs/api/event_reduction.md @@ -1 +1 @@ -::: lr_reduction.event_reduction \ No newline at end of file +::: lr_reduction.event_reduction diff --git a/docs/api/output.md b/docs/api/output.md index a49611b..732dc54 100644 --- a/docs/api/output.md +++ b/docs/api/output.md @@ -1 +1 @@ -::: lr_reduction.output \ No newline at end of file +::: lr_reduction.output diff --git a/docs/api/peak_finding.md b/docs/api/peak_finding.md index 1c14c96..01b440f 100644 --- a/docs/api/peak_finding.md +++ b/docs/api/peak_finding.md @@ -1 +1 @@ -::: lr_reduction.peak_finding \ No newline at end of file +::: lr_reduction.peak_finding diff --git a/docs/api/reduction_template_reader.md b/docs/api/reduction_template_reader.md index 22cf862..607b495 100644 --- a/docs/api/reduction_template_reader.md +++ b/docs/api/reduction_template_reader.md @@ -1 +1 @@ -::: lr_reduction.reduction_template_reader \ No newline at end of file +::: lr_reduction.reduction_template_reader diff --git a/docs/api/template.md b/docs/api/template.md index 9774ae4..46c5766 100644 --- a/docs/api/template.md +++ b/docs/api/template.md @@ -1 +1 @@ -::: lr_reduction.template \ No newline at end of file +::: lr_reduction.template diff --git a/docs/api/time_resolved.md b/docs/api/time_resolved.md index 1a1f1bb..1e82b73 100644 --- a/docs/api/time_resolved.md +++ b/docs/api/time_resolved.md @@ -1 +1 @@ -::: lr_reduction.time_resolved \ No newline at end of file +::: lr_reduction.time_resolved diff --git a/docs/api/utils.md b/docs/api/utils.md index 89529da..972f7b9 100644 --- a/docs/api/utils.md +++ b/docs/api/utils.md @@ -1 +1 @@ -::: lr_reduction.utils \ No newline at end of file +::: lr_reduction.utils diff --git a/docs/api/workflow.md b/docs/api/workflow.md index 663c631..8269495 100644 --- a/docs/api/workflow.md +++ b/docs/api/workflow.md @@ -1 +1 @@ -::: lr_reduction.workflow \ No newline at end of file +::: lr_reduction.workflow diff --git a/docs/developer/developer.md b/docs/developer/developer.md index 61e76fb..ac96d83 100644 --- a/docs/developer/developer.md +++ b/docs/developer/developer.md @@ -131,7 +131,8 @@ git push origin --tags main ``` - _minor_ or _major_ release, we create a stable release _after_ we have created a Candidate release. - For this customary procedure, follow: + For this customary procedure, follow: + - The [Software Maturity Model](https://ornl-neutrons.atlassian.net/wiki/spaces/NDPD/pages/23363585/Software+Maturity+Model) for continous versioning as well as creating release candidates and stable releases. - Update the :ref:`Release Notes ` with major fixes, updates and additions since last stable release. diff --git a/docs/index.md b/docs/index.md index e4e4466..d0f98aa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,10 +5,10 @@ - [Conda Environments](./user/conda_environments.md) - [Releases](./releases.md) - ### Contacting the Team -The best mechanism for a user to request a change or report a bug is to contact the SANS CIS. +The best mechanism for a user to request a change or report a bug is to contact the SANS CIS. + Please email [Mathieu Doucet](mailto:doucetm@ornl.gov) with your request. A change needs to be in the form of a: @@ -20,7 +20,6 @@ A change needs to be in the form of a: - [lr_reduction](source/api/lr_reduction.md) - ## Developer Guide - [Contributing Guide](source/developer/contributing.md) diff --git a/docs/releases.md b/docs/releases.md index 6f75297..34873a3 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -2,7 +2,7 @@ Notes for major or minor releases. Notes for patch releases are deferred. -Release notes are written in reverse chronological order, with the most recent release at the top, +Release notes are written in reverse chronological order, with the most recent release at the top, using the following format: ```markdown diff --git a/reduction/lr_reduction/DeadTimeCorrection.py b/reduction/lr_reduction/DeadTimeCorrection.py index cdc19f2..f36ccab 100644 --- a/reduction/lr_reduction/DeadTimeCorrection.py +++ b/reduction/lr_reduction/DeadTimeCorrection.py @@ -2,12 +2,12 @@ Dead time correction algorithm for single-readout detectors. """ +import numpy as np +import scipy from mantid.api import * from mantid.api import AlgorithmFactory, PythonAlgorithm -from mantid.simpleapi import * from mantid.kernel import * -import numpy as np -import scipy +from mantid.simpleapi import * class SingleReadoutDeadTimeCorrection(PythonAlgorithm): @@ -94,4 +94,4 @@ def PyExec(self): self.setProperty('OutputWorkspace', counts_ws) -AlgorithmFactory.subscribe(SingleReadoutDeadTimeCorrection) \ No newline at end of file +AlgorithmFactory.subscribe(SingleReadoutDeadTimeCorrection) diff --git a/reduction/lr_reduction/__init__.py b/reduction/lr_reduction/__init__.py index f3716b6..cc5c453 100644 --- a/reduction/lr_reduction/__init__.py +++ b/reduction/lr_reduction/__init__.py @@ -1,4 +1,4 @@ try: - from ._version import __version__ # noqa: F401 + from ._version import __version__ except ImportError: __version__ = "unknown" diff --git a/reduction/lr_reduction/event_reduction.py b/reduction/lr_reduction/event_reduction.py index 9b876b1..0b6cea5 100644 --- a/reduction/lr_reduction/event_reduction.py +++ b/reduction/lr_reduction/event_reduction.py @@ -564,7 +564,7 @@ def norm_bck_subtraction(self): return background.side_background(self._ws_db, self, self.norm_peak, self.norm_bck, self.norm_low_res, normalize_to_single_pixel=False) - def slice(self, x_min=0.002, x_max=0.004, x_bins=None, z_bins=None, # noqa A003 + def slice(self, x_min=0.002, x_max=0.004, x_bins=None, z_bins=None, refl=None, d_refl=None, normalize=False): """ Retrieve a slice from the off-specular data. diff --git a/reduction/lr_reduction/scaling_factors/LRDirectBeamSort.py b/reduction/lr_reduction/scaling_factors/LRDirectBeamSort.py index 80fd7be..e5742a5 100644 --- a/reduction/lr_reduction/scaling_factors/LRDirectBeamSort.py +++ b/reduction/lr_reduction/scaling_factors/LRDirectBeamSort.py @@ -5,14 +5,15 @@ # Institut Laue - Langevin & CSNS, Institute of High Energy Physics, CAS # SPDX - License - Identifier: GPL - 3.0 + # pylint: disable=no-init,invalid-name -from mantid.api import * -from mantid.simpleapi import * -from mantid.kernel import * -import functools -import numpy as np -from typing import List, Tuple import datetime +import functools from math import ceil +from typing import List, Tuple + +import numpy as np +from mantid.api import * +from mantid.kernel import * +from mantid.simpleapi import * THI_TOLERANCE = 0.002 diff --git a/reduction/lr_reduction/scaling_factors/LRScalingFactors.py b/reduction/lr_reduction/scaling_factors/LRScalingFactors.py index 1a0d58d..2446a7c 100644 --- a/reduction/lr_reduction/scaling_factors/LRScalingFactors.py +++ b/reduction/lr_reduction/scaling_factors/LRScalingFactors.py @@ -8,9 +8,10 @@ import os import re import time + from mantid.api import * -from mantid.simpleapi import * from mantid.kernel import * +from mantid.simpleapi import * import lr_reduction from lr_reduction import DeadTimeCorrection diff --git a/reduction/test/test_dead_time.py b/reduction/test/test_dead_time.py index 60ca998..f44862a 100644 --- a/reduction/test/test_dead_time.py +++ b/reduction/test/test_dead_time.py @@ -1,18 +1,16 @@ +import mantid.simpleapi as mtd_api +from lr_reduction import template from lr_reduction.DeadTimeCorrection import SingleReadoutDeadTimeCorrection +from lr_reduction.utils import amend_config -import mantid -import mantid.simpleapi as mtd_api mtd_api.config["default.facility"] = "SNS" mtd_api.config["default.instrument"] = "REF_L" -from lr_reduction import event_reduction, template, workflow -from lr_reduction.utils import amend_config - def test_deadtime(nexus_dir): """ - Test the time-resolved reduction that uses a measured reference. - It is generally used at 30 Hz but it also works at 60 Hz. + Test the time-resolved reduction that uses a measured reference. + It is generally used at 30 Hz but it also works at 60 Hz. """ with amend_config(data_dir=nexus_dir): ws = mtd_api.Load("REF_L_198409") @@ -22,16 +20,17 @@ def test_deadtime(nexus_dir): algo.setProperty("InputWorkspace", ws) algo.setProperty("OutputWorkspace", "dead_time_corr") algo.PyExec() - corr_ws = algo.getProperty('OutputWorkspace').value + corr_ws = algo.getProperty("OutputWorkspace").value corr = corr_ws.readY(0) for c in corr: - assert(c>0) - assert(c<1.001) + assert c > 0 + assert c < 1.001 + def test_deadtime_paralyzable(nexus_dir): """ - Test the time-resolved reduction that uses a measured reference. - It is generally used at 30 Hz but it also works at 60 Hz. + Test the time-resolved reduction that uses a measured reference. + It is generally used at 30 Hz but it also works at 60 Hz. """ with amend_config(data_dir=nexus_dir): ws = mtd_api.Load("REF_L_198409") @@ -42,17 +41,18 @@ def test_deadtime_paralyzable(nexus_dir): algo.setProperty("Paralyzable", True) algo.setProperty("OutputWorkspace", "dead_time_corr") algo.PyExec() - corr_ws = algo.getProperty('OutputWorkspace').value + corr_ws = algo.getProperty("OutputWorkspace").value corr = corr_ws.readY(0) for c in corr: - assert(c>0) - assert(c<1.001) + assert c > 0 + assert c < 1.001 + def test_full_reduction(nexus_dir): """ - Test dead time from the reduction workflow + Test dead time from the reduction workflow """ - template_path = 'data/template.xml' + template_path = "data/template.xml" with amend_config(data_dir=nexus_dir): ws = mtd_api.Load("REF_L_198409") @@ -65,8 +65,7 @@ def test_full_reduction(nexus_dir): template_data.dead_time = False _, r2, _ = template.process_from_template_ws(ws, template_data) - corr = r1/r2 + corr = r1 / r2 for c in corr: - assert(c>0) - assert(c<1.001) - + assert c > 0 + assert c < 1.001 diff --git a/reduction/test/test_scaling_factors.py b/reduction/test/test_scaling_factors.py index a0992d3..fb1ba65 100644 --- a/reduction/test/test_scaling_factors.py +++ b/reduction/test/test_scaling_factors.py @@ -1,17 +1,13 @@ import os -import numpy as np - -from lr_reduction.DeadTimeCorrection import SingleReadoutDeadTimeCorrection -import mantid import mantid.simpleapi as mtd_api +import numpy as np + mtd_api.config["default.facility"] = "SNS" mtd_api.config["default.instrument"] = "REF_L" -from lr_reduction import event_reduction, template, workflow -from lr_reduction.utils import amend_config - from lr_reduction.scaling_factors import workflow as sf_workflow +from lr_reduction.utils import amend_config def check_results(data_file, reference): @@ -172,4 +168,3 @@ def test_compute_sf_with_deadtime_tof_200_sort(nexus_dir): assert output is True check_results(output_cfg, 'data/sf_197912_Si_dt_par_46_200.cfg') - From 7a9231a993735c11be16faee82bcc7f7a9b970ea Mon Sep 17 00:00:00 2001 From: glass-ships Date: Mon, 6 Jan 2025 13:47:46 -0500 Subject: [PATCH 3/3] remove docs-sphinx dir --- docs-sphinx/Makefile | 195 ------------------ docs-sphinx/conf.py | 74 ------- docs-sphinx/index.rst | 42 ---- docs-sphinx/make.bat | 35 ---- docs-sphinx/source/api/lr_reduction.rst | 81 -------- docs-sphinx/source/developer/contributing.rst | 19 -- docs-sphinx/source/developer/developer.rst | 141 ------------- docs-sphinx/source/releases.rst | 38 ---- .../source/user/conda_environments.rst | 29 --- 9 files changed, 654 deletions(-) delete mode 100644 docs-sphinx/Makefile delete mode 100644 docs-sphinx/conf.py delete mode 100644 docs-sphinx/index.rst delete mode 100644 docs-sphinx/make.bat delete mode 100644 docs-sphinx/source/api/lr_reduction.rst delete mode 100644 docs-sphinx/source/developer/contributing.rst delete mode 100644 docs-sphinx/source/developer/developer.rst delete mode 100644 docs-sphinx/source/releases.rst delete mode 100644 docs-sphinx/source/user/conda_environments.rst diff --git a/docs-sphinx/Makefile b/docs-sphinx/Makefile deleted file mode 100644 index 96fe2a3..0000000 --- a/docs-sphinx/Makefile +++ /dev/null @@ -1,195 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. - -# Options should be aligned with how the documentation is built on RTD -# (except for '--keep-going', failing fast is prefered on local builds) -# We also remove '-E' to reduce the time of rebuilding reference indexes -# on each build. -SPHINXOPTS = -T -j auto -W -SPHINXBUILD = sphinx-build -PAPER = -PROJECT ?= lr_reduction -BUILDDIR = build - -# Do not use local Django settings during the docs build -export DJANGO_SETTINGS_SKIP_LOCAL = True - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -auto: - sphinx-autobuild --port 8888 $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -livehtml: - sphinx-autobuild --port 4444 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/sdf.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/sdf.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/sdf" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/sdf" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs-sphinx/conf.py b/docs-sphinx/conf.py deleted file mode 100644 index 6dc63c6..0000000 --- a/docs-sphinx/conf.py +++ /dev/null @@ -1,74 +0,0 @@ -"""Configuration file for the Sphinx documentation builder. -For the full list of built-in configuration values, see the documentation: -https://www.sphinx-doc.org/en/master/usage/configuration.html -""" -import os -import sys -import versioningit - -sys.path.insert(0, os.path.abspath("../reduction")) - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "lr_reduction" -copyright = "2024, ORNL" # noqa A001 -author = "ORNL" -version = versioningit.get_version("../") -# The full version, including alpha/beta/rc tags -release = "source/".join(version.split("source/")[:-1]) - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - "sphinx.ext.duration", - "sphinx.ext.doctest", - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", - "sphinx.ext.intersphinx", - "sphinx.ext.viewcode", - "sphinx.ext.coverage", -] - -autodoc_mock_imports = [ - "mantid", - "mantid.api", - "mantid.kernel", - "mantid.utils", - "mantid.utils.logging", - "mantid.simpleapi", - "mantid.geometry", - "mantidqt.widgets", - "mantidqt.widgets.algorithmprogress", - "qtpy", - "qtpy.uic", - "qtpy.QtWidgets", - "mantidqt", - "mantid.plots", - "mantid.plots.plotfunctions", - "mantid.plots.datafunctions", - "mantid.plots.utility", -] - -master_doc = "index" - -intersphinx_mapping = { - "python": ("https://docs.python.org/3/", None), - "sphinx": ("https://www.sphinx-doc.org/en/master/", None), -} -intersphinx_disabled_domains = ["std"] - -templates_path = ["_templates"] -exclude_patterns = ["_build"] -pygments_style = "sphinx" - - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = "sphinx_rtd_theme" # pylint: disable=C0103 - -html_theme_options = {"style_nav_header_background": "#472375"} - -epub_show_urls = "footnote" # pylint: disable=C0103 diff --git a/docs-sphinx/index.rst b/docs-sphinx/index.rst deleted file mode 100644 index 2447dcf..0000000 --- a/docs-sphinx/index.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. :lr_reduction: - -Welcome to lr_reduction (Liquids Reflectometer Reduction) documentation -======================================================================= - -User Guide ----------- - -.. toctree:: - :titlesonly: - - /source/user/conda_environments - /source/releases - -Contacting the Team -+++++++++++++++++++ -The best mechanism for a user to request a change or report a bug is to contact the SANS CIS. -Please email `Mathieu Doucet`_ with your request. - -.. _Mathieu Doucet: doucetm@ornl.gov - -A change needs to be in the form of a: - -- Story for any enhancement request -- Defect for any bug fix request. - -API ---- - -.. toctree:: - :titlesonly: - - /source/api/lr_reduction - -Developer Guide ---------------- - -.. toctree:: - :titlesonly: - - /source/developer/contributing - /source/developer/developer diff --git a/docs-sphinx/make.bat b/docs-sphinx/make.bat deleted file mode 100644 index 9534b01..0000000 --- a/docs-sphinx/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs-sphinx/source/api/lr_reduction.rst b/docs-sphinx/source/api/lr_reduction.rst deleted file mode 100644 index 213ae65..0000000 --- a/docs-sphinx/source/api/lr_reduction.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. api_lr_reduction: - -lr_reduction package -==================== - -.. contents:: - :local: - :depth: 1 - -lr_reduction.background ------------------------ - -.. automodule:: lr_reduction.background - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.event_reduction ----------------------------- - -.. automodule:: lr_reduction.event_reduction - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.output -------------------- - -.. automodule:: lr_reduction.output - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.peak_finding -------------------------- - -.. automodule:: lr_reduction.peak_finding - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.reduction_template_reader --------------------------------------- - -.. automodule:: lr_reduction.reduction_template_reader - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.template ---------------------- - -.. automodule:: lr_reduction.template - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.time_resolved --------------------------- - -.. automodule:: lr_reduction.time_resolved - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.utils ------------------- - -.. automodule:: lr_reduction.utils - :members: - :undoc-members: - :show-inheritance: - -lr_reduction.workflow ---------------------- - -.. automodule:: lr_reduction.workflow - :members: - :undoc-members: - :show-inheritance: - diff --git a/docs-sphinx/source/developer/contributing.rst b/docs-sphinx/source/developer/contributing.rst deleted file mode 100644 index 847e838..0000000 --- a/docs-sphinx/source/developer/contributing.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. contributing - -Guide to Contributing -===================== - -Contributions to this project are welcome. All contributors agree to the following: - -- It is assumed that the contributor is an ORNL employee and belongs to the development team. - Thus the following instructions are specific to ORNL development team's process. -- You have permission and any required rights to submit your contribution. -- Your contribution is provided under the license of this project and may be redistributed as such. -- All contributions to this project are public. - -All contributions must be "signed off" in the commit log and by doing so you agree to the above. - -Getting access to the main project ----------------------------------- -Direct commit access to the project is currently restricted to core developers. -All other contributions should be done through pull requests. diff --git a/docs-sphinx/source/developer/developer.rst b/docs-sphinx/source/developer/developer.rst deleted file mode 100644 index 39e026b..0000000 --- a/docs-sphinx/source/developer/developer.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. _developer_documentation: - -Developer Documentation -======================= - -.. contents:: - :local: - :depth: 1 - -Local Environment ------------------ -For purposes of development, create conda environment `lr_reduction` with file `environment.yml`, and then -install the package in development mode with `pip`: - -.. code-block:: bash - - $> cd /path/to/lr_reduction/ - $> conda create env --solver libmamba --file ./environment.yml - $> conda activate lr_reduction - (lr_reduction)$> pip install -e ./ - -By installing the package in development mode, one doesn't need to re-install package `lr_reduction` in conda -environment `lr_reduction` after every change to the source code. - -pre-commit Hooks ----------------- - -Activate the hooks by typing in the terminal: - -.. code-block:: bash - - $> cd cd /path/to/mr_reduction/ - $> conda activate mr_reduction - (mr_reduction)$> pre-commit install - -Development procedure ---------------------- - -1. A developer is assigned with a task during neutron status meeting and changes the task's status to **In Progress**. -2. The developer creates a branch off *next* and completes the task in this branch. -3. The developer creates a pull request (PR) off *next*. -4. Any new features or bugfixes must be covered by new and/or refactored automated tests. -5. The developer asks for another developer as a reviewer to review the PR. - A PR can only be approved and merged by the reviewer. -6. The developer changes the task’s status to **Complete** and closes the associated issue. - -Updating mantid dependency --------------------------- -The mantid version and the mantid conda channel (`mantid/label/main` or `mantid/label/nightly`) **must** be -synchronized across these files: - -- environment.yml -- conda.recipe/meta.yml -- .github/workflows/package.yml - -Using the Data Repository liquidsreflectometer-data ---------------------------------------------------- -To run the integration tests in your local environment, it is necessary first to download the data files. -Because of their size, the files are stored in the Git LFS repository -`lr_reduction-data `_. - -It is necessary to have package `git-lfs` installed in your machine. - -.. code-block:: bash - - $> sudo apt install git-lfs - -After this step, initialize or update the data repository: - -.. code-block:: bash - - $> cd /path/to/lr_reduction - $> git submodule update --init - -This will either clone `liquidsreflectometer-data` into `/path/to/lr_reduction/tests/liquidsreflectometer-data` or -bring the `liquidsreflectometer-data`'s refspec in sync with the refspec listed within file -`/path/to/liquidsreflectometer/.gitmodules`. - -An intro to Git LFS in the context of the Neutron Data Project is found in the -`Confluence pages `_ -(login required). - - -Coverage reports ----------------- - -GitHuh actions create reports for unit and integration tests, then combine into one report and upload it to -`Codecov `_. - - -Building the documentation --------------------------- -A repository webhook is setup to automatically trigger the latest documentation build by GitHub actions. -To manually build the documentation: - -.. code-block:: bash - - $> conda activate lr_reduction - (lr_reduction)$> make docs - -After this, point your browser to -`file:///path/to/lr_reduction/docs/build/html/index.html` - - -Creating a stable release -------------------------- - -- *patch* release, it may be allowed to bypass the creation of a candidate release. - Still, we must update branch `qa` first, then create the release tag in branch `main`. - For instance, to create patch version "v2.1.1": - -.. code-block:: bash - - VERSION="v2.1.2" - # update the local repository - git fetch --all --prune - git fetch --prune --prune-tags origin - # update branch qa from next, possibly bringing work done in qa missing in next - git switch next - git rebase -v origin/next - git merge --no-edit origin/qa # commit message is automatically generated - git push origin next # required to "link" qa to next, for future fast-forward - git switch qa - git rebase -v origin/qa - git merge --ff-only origin/next - # update branch main from qa - git merge --no-edit origin/main # commit message is automatically generated - git push origin qa # required to "link" main to qa, for future fast-forward - git switch main - git rebase -v origin/main - git merge --ff-only origin/qa - git tag $VERSION - git push origin --tags main - -- *minor* or *major* release, we create a stable release *after* we have created a Candidate release. - For this customary procedure, follow: - - + the `Software Maturity Model `_ for continous versioning as well as creating release candidates and stable releases. - + Update the :ref:`Release Notes ` with major fixes, updates and additions since last stable release. - - diff --git a/docs-sphinx/source/releases.rst b/docs-sphinx/source/releases.rst deleted file mode 100644 index 47b3161..0000000 --- a/docs-sphinx/source/releases.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _release_notes: - -Release Notes -============= -Notes for major or minor releases. Notes for patch releases are deferred - - ------------------------------ -(date of release, format YYYY-MM-DD) - -**Of interest to the User**: - -- PR #XYZ one-liner description - -**Of interest to the Developer:** - -- PR #40 documentation to create a patch release - -2.1.0 ------ - -**Of interest to the User**: - -- PR #33 enable dead time correction for runs with skipped pulses -- PR #26 add dead time correction to the computation of scaling factors -- PR #23 add dead time correction -- PR #19 Functionality to use two backgrounds -- PR #15 Ability to fit a background with a polynomial function - -**Of interest to the Developer:** - -- PR #37 documentation conforming to that of the python project template -- PR #36 versioning with versioningit -- PR #25 Read in error events when computing correction -- PR #21 switch dependency from mantidworkbench to mantid -- PR #20 allow runtime initialization of new attributes for ReductionParameters -- PR #14 add first GitHub actions -- PR #12 switch from mantid to mantidworkbench conda package diff --git a/docs-sphinx/source/user/conda_environments.rst b/docs-sphinx/source/user/conda_environments.rst deleted file mode 100644 index 7f2ec71..0000000 --- a/docs-sphinx/source/user/conda_environments.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. conda_environments - -Conda Environments -================== - -Three conda environments are available in the analysis nodes, beamline machines, as well as the -jupyter notebook severs. On a terminal: - -.. code-block:: bash - - $> conda activate - -where `` is one of `lr_reduction`, `lr_reduction-qa`, and `lr_reduction-dev` - -lr_reduction Environment ------------------------- -Activates the latest stable release of `lr_reduction`. Typically users will reduce their data in this environment. - -lr_reduction-qa Environment ---------------------------- -Activates a release-candidate environment. -Instrument scientists and computational instrument scientists will carry out testing on this environment -to prevent bugs being introduce in the next stable release. - -lr_reduction-dev Environment ----------------------------- -Activates the environment corresponding to the latest changes in the source code. -Instrument scientists and computational instrument scientists will test the latest changes to `lr_reduction` in this -environment.