diff --git a/.gitignore b/.gitignore index 938f7f37..6028f484 100644 --- a/.gitignore +++ b/.gitignore @@ -129,3 +129,4 @@ dmypy.json .pyre/ src/shiver/_version.py +.vscode/launch.json diff --git a/README.md b/README.md index 459d9a83..fcfd111b 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,24 @@ To set the pre-commit hook before each git commit pre-commit install ``` +--- +**NOTE** + +When adding new views, presenters and methods. Please navigate to docs/source/repo_doc.rst. Add the new feature under the appropriate section following the given template: + +```bash +.. automodule:: path.to.new.module + :members: +``` + +Once complete, rebuild the documentation: + + cd SHIVER/docs/ + make clean + make html + +--- + [![CI](https://github.com/neutrons/Shiver/actions/workflows/actions.yml/badge.svg?branch=next)](https://github.com/neutrons/Shiver/actions/workflows/actions.yml) [![codecov](https://codecov.io/gh/neutrons/shiver/branch/next/graph/badge.svg?token=J1ZNHXF6Ml)](https://codecov.io/gh/neutrons/shiver) [![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/7381/badge)](https://bestpractices.coreinfrastructure.org/projects/7381) diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..9d29d715 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,21 @@ +# Purpose: Convenience scripts to simplify some common Sphinx operations, such as rendering the content. + +# Minimal makefile for Sphinx documentation + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..5a41d8d3 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,37 @@ +REM Purpose: Convenience scripts to simplify some common Sphinx operations, such as rendering the content. + +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%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.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..de9b65d5 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,54 @@ +""" + Purpose: A Python script holding the configuration of the project. Contains the project + name and release information as well as some extra configuration keys. +""" +import os +import sys +import versioningit + + +sys.path.insert(0, os.path.abspath("../../")) + +# 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 + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "SHIVER" # pylint: disable=C0103 +copyright = "2022, ORNL" # pylint: disable=W0622, C0103 +author = "ORNL" # pylint: disable=C0103 +version = versioningit.get_version("../../") +release = ".".join(version.split(".")[:-1]) # pylint: disable=C0103 + +# -- 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", +] + +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 = [] + + +# -- 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/getting_started.rst b/docs/source/getting_started.rst new file mode 100644 index 00000000..1c501465 --- /dev/null +++ b/docs/source/getting_started.rst @@ -0,0 +1,67 @@ +Getting Started +=============== + +.. _getting_started: + + + +Instructions for SHIVER development +----------------------------------- + +Conda Configuration +``````````````````` +Create and activate conda environment for ``SHIVER``. + +.. code-block:: sh + + conda env create --file environment.yml + # or + mamba env create --file environment.yml + + conda activate shiver + +Install ``SHIVER`` (in `editable mode `_) and start application + +.. code-block:: sh + + python -m pip install -e . + + shiver + +If it has been a while, once can update using + +.. code-block:: sh + + conda activate shiver + conda env update --file environment.yml --prune + +To start ``SHIVER`` from within the Mantid workbench, start ``mantidworkbench`` then run the following in the +``IPython`` console + +.. code-block:: sh + + from shiver import Shiver + s = Shiver() + s.show() + +**For Developers** + +To run all tests for ``SHIVER`` + +.. code-block:: sh + + pytest + #or + python -m pytest + +To run ``pre-commit`` manually + +.. code-block:: sh + + pre-commit run --all-files + +Or to set the ``pre-commit`` hook before each ``git`` commit + +.. code-block:: sh + + pre-commit install diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..62a645e7 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,35 @@ +.. Purpose: The root document of the project, which serves as welcome page and contains the root +.. of the "table of contents tree" (or toctree). + +Welcome to SHIVER's documentation! +================================== +The Spectroscopy HIstogram Visualizer for Event Reduction **(SHIVER)** is a tool to +allow examination of time of flight inelastic neutron data, from single crystal, +direct geometry experiments. It is intended to perform the following tasks: + +* Transform time of flight data from multiple orientations into a single intermediate + structure in units of reciprocal space and energy transfer. + + +* Allow slicing of the intermediate file and creation of histograms containing S(**Q**, ∆ *E*) + with various dimensionality + + +* Visualize the histograms + +Check out the :doc:`usage` section for further information, including :ref:`installation` +steps for this project. + +.. note:: + + This project is under active development. + +Contents +-------- + +.. toctree:: + :maxdepth: 1 + + getting_started + usage + repo_doc diff --git a/docs/source/repo_doc.rst b/docs/source/repo_doc.rst new file mode 100644 index 00000000..73a4ec95 --- /dev/null +++ b/docs/source/repo_doc.rst @@ -0,0 +1,97 @@ +Repository Documentation +======================== + +Shiver +------ +.. automodule:: src.shiver.shiver + :members: + +Models +------ + +.. automodule:: src.shiver.models.sample + :members: + +.. automodule:: src.shiver.models.help + :members: + +.. automodule:: src.shiver.models.generate + :members: + +.. automodule:: src.shiver.models.convert_dgs_to_single_mde + :members: + +.. automodule:: src.shiver.models.makeslice + :members: + +.. automodule:: src.shiver.models.generate_dgs_mde + :members: + +.. automodule:: src.shiver.models.corrections + :members: + +.. automodule:: src.shiver.models.utils + :members: + +.. automodule:: src.shiver.models.histogram + :members: + +Presenters +---------- + +.. automodule:: src.shiver.presenters.sample + :members: + +.. automodule:: src.shiver.presenters.generate + :members: + +.. automodule:: src.shiver.presenters.histogram + :members: + +Views +----- + +.. automodule:: src.shiver.views.histogram_parameters + :members: + +.. automodule:: src.shiver.views.sample + :members: + +.. automodule:: src.shiver.views.invalid_styles + :members: + +.. automodule:: src.shiver.views.oncat + :members: + +.. automodule:: src.shiver.views.generate + :members: + +.. automodule:: src.shiver.views.advanced_options + :members: + +.. automodule:: src.shiver.views.data + :members: + +.. automodule:: src.shiver.views.loading_buttons + :members: + +.. automodule:: src.shiver.views.workspace_tables + :members: + +.. automodule:: src.shiver.views.plots + :members: + +.. automodule:: src.shiver.views.mainwindow + :members: + +.. automodule:: src.shiver.views.reduction_parameters + :members: + +.. automodule:: src.shiver.views.corrections + :members: + +.. automodule:: src.shiver.views.polarized_options + :members: + +.. automodule:: src.shiver.views.histogram + :members: diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 00000000..9add1aea --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,38 @@ +Usage +===== + +.. _installation: + +Installation +------------ + + +Under Construction! + +Application Information +----------------------- + +``SHIVER`` is a desktop application for generating histograms from direct +geometry inelastic data related to spectroscopy event reduction. It is +built as a python package and can be used either as a standalone application +or as a package imported in Mantid workbench. + +.. note:: + `Github Shiver Repository `_ + +Technologies +------------ + +The project is written in Python (>=3.8). It is highly dependent on `Manitd `_. +The Graphical User Interface (GUI) is based on `QtPy `_ (version is defined by Mantid) + + +Project Structure +----------------- + +The main code of the project is at src/shiver and the tests are at ``tests/`` +folders. The project contains additional scripts at ``DGS_SC_scripts/`` folder, +which are initial scripts that ``SHIVER`` was created around. + +The code follows the `MVP (Model-View-Presenter) `_ Thus, +all current and future changes will follow this pattern. diff --git a/environment.yml b/environment.yml index 80a479a6..feb3a4c1 100644 --- a/environment.yml +++ b/environment.yml @@ -10,6 +10,8 @@ dependencies: - pytest=7.2.1 - pytest-qt=4.2.0 - pytest-cov=4.0.0 + - sphinx - pip - pip: - https://oncat.ornl.gov/packages/pyoncat-1.4.1-py3-none-any.whl + - sphinx-rtd-theme diff --git a/src/shiver/views/oncat.py b/src/shiver/views/oncat.py index c0141c96..ad04ed19 100644 --- a/src/shiver/views/oncat.py +++ b/src/shiver/views/oncat.py @@ -606,7 +606,7 @@ def get_dataset_info( # pylint: disable=too-many-branches If any of the include_runs is already in the dataset If any of the exclude_runs is not already accounted for If no runs were found to match the criteria (for example, - dataset_name=None and include_runs=None) + dataset_name=None and include_runs=None) """ # get run number, angle, and sequence names from oncat projection = ["indexed.run_number", f"metadata.entry.daslogs.{angle_pv}"]