diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..9d29d71 --- /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/conf.py b/docs/conf.py index d4add68..974a5aa 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,78 +1,70 @@ -"""Documentation Configuration""" +"""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 +""" -# 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 +# import versioningit sys.path.insert(0, os.path.abspath("../src")) # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = "Project Name" -copyright = "Copyright 2024" # noqa A001 -author = "Author Name" - -# The short X.Y version -# NOTE: need to specify the location of the pyproject.toml file instead of the -# location of the source tree -version = versioningit.get_version("..") -# The full version, including alpha/beta/rc tags -release = ".".join(version.split(".")[:-1]) +project = "hyspecplanningtools" +copyright = "2024, ORNL" # noqa A001 +author = "ORNL" +# version = versioningit.get_version("../../") +# # The full version, including alpha/beta/rc tags +# release = ".".join(version.split(".")[:-1]) # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", + "sphinx.ext.duration", "sphinx.ext.doctest", - "sphinx.ext.todo", - "sphinx.ext.coverage", - "sphinx.ext.mathjax", - "sphinx.ext.ifconfig", - "sphinx.ext.viewcode", - "sphinx.ext.githubpages", + "sphinx.ext.autodoc", "sphinx.ext.intersphinx", - "sphinx.ext.napoleon", - "myst_parser", + "sphinx.ext.viewcode", + "sphinx.ext.coverage", + "sphinxcontrib.mermaid", ] -templates_path = ["_templates"] -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -source_suffix = [".rst", ".md"] +autodoc_mock_imports = [ + "qtpy", + "qtpy.uic", + "qtpy.QtWidgets", +] -# The master toctree document. master_doc = "index" +source_suffix = [".rst", ".md"] -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +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 -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" # please add corresponding package to environment.yml if you want to use it -autosummary_generate = True +html_theme = "sphinx_rtd_theme" # pylint: disable=C0103 -# Napoleon settings -napoleon_google_docstring = False -napoleon_numpy_docstring = True +html_theme_options = {"style_nav_header_background": "#472375"} -# "Static" resources (like *.css *.js files, or images) to be included when generating the HTML documentation. -if os.path.exists("_static"): - html_static_path = ["_static"] +html_static_path = ["_static"] + +html_css_files = [ + "css/custom.css", +] -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True +epub_show_urls = "footnote" # pylint: disable=C0103 diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index b3000f3..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -========================================= -Welcome to python project template docs! -========================================= - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - README - -========================================= -Indices and tables -========================================= - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..793c5ab --- /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/_static/css/custom.css b/docs/source/_static/css/custom.css new file mode 100644 index 0000000..95c0eb2 --- /dev/null +++ b/docs/source/_static/css/custom.css @@ -0,0 +1,11 @@ +/* makes the width expand the entire width*/ +.wy-nav-content { + min-width: 360px; + max-width: 100%; +} + +/* allows table to be multi-line */ +table.docutils td { + word-wrap:break-word; + white-space:pre-wrap; +} diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..726064b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,70 @@ +"""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("../../src")) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "Hyspecplanningtools" +copyright = "2024, ORNL" # noqa A001 +author = "ORNL" +# version = versioningit.get_version("../../") +# # The full version, including alpha/beta/rc tags +# release = ".".join(version.split(".")[:-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.intersphinx", + "sphinx.ext.viewcode", + "sphinx.ext.coverage", + "sphinxcontrib.mermaid", +] + +autodoc_mock_imports = [ + "qtpy", + "qtpy.uic", + "qtpy.QtWidgets", +] + +master_doc = "index" +source_suffix = [".rst", ".md"] + +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"} + +html_static_path = ["_static"] + +html_css_files = [ + "css/custom.css", +] + +epub_show_urls = "footnote" # pylint: disable=C0103 diff --git a/docs/source/design/index.rst b/docs/source/design/index.rst new file mode 100644 index 0000000..6041458 --- /dev/null +++ b/docs/source/design/index.rst @@ -0,0 +1,19 @@ +.. _design__guidelines: + +============================= +Hyspecplanningtools Design +============================= + +Information, diagrams and flowcharts are included about the various components of the polarization tool. +Please make sure to +review and adhere to these guidelines when contributing to the project. + + +Contents +-------- + +.. toctree:: + :maxdepth: 2 + + polarizationmodel + polarizationflow diff --git a/docs/source/design/polarizationflow.rst b/docs/source/design/polarizationflow.rst new file mode 100644 index 0000000..a14d6eb --- /dev/null +++ b/docs/source/design/polarizationflow.rst @@ -0,0 +1,152 @@ +.. _polarizationflow: + +=============================== +Fields and Validation for Plot +=============================== + +The main functionality of the tool is to display a plot, based on the filled in parameters, automatically; no plot button exists + +Overall, users can: + * plot from Powder + * plot from Single Crystal + * click on "Help" button that opens up a readthedocs user documentation + +Fields +-------- + +Below are the fields of SingleCrystal and Powder Models + +.. list-table:: Common Fields + :header-rows: 1 + + * - Field + - Type + - Value Origin + - Additional validation + - Mandatory + * - Polarization Type + - String + - predefined choices:["Powder", "Single Crystal"] + - + - yes + * - Ei (Incident Energy) - meV + - Double + - + - 1 < Ei < 100 + - yes + * - S2 (HYSPEC Detector Tank Angle) + - String + - + - 30<=P<=90 + - yes + * - P (Polarization Direction Angle) + - Double + - + - -90<=P<=90 + - yes + * - Delta E + - Double + - + - Delta E<=Ei + - no + * - mod Q (\|Q\|) + - Double + - + - + - no + * - Plot Type + - String + - predefined choices:["cos^2(alpha)", "(1+cos^2alpha)/2"] + - + - yes + + +Below are the additional fields of SingleCrystal Model + + +.. list-table:: Single Crystal Model Additional Fields + :header-rows: 1 + + * - Field + - Type + - Value Origin + - Additional validation + - Mandatory + * - a + - Double + - + - 1 < a < 100 + - yes + * - b + - Double + - + - 1 < b < 100 + - yes + * - c + - Double + - + - 1 < c < 100 + - yes + * - alpha + - Double + - + - 45 < alpha < 135 + - yes + * - beta + - Double + - + - 45 < beta < 135 + - yes + * - gamma + - Double + - + - 45 < gamma < 135 + - yes + * - H + - Double + - + - + - yes + * - K + - Double + - + - + - yes + * - L + - Double + - + - + - yes + + + +Inter-Field Validations +------------------------ + +Polarization Type: + * If Polarization Type set to "Single Crystal", all parameters of Single Crystal block are required. + * If Polarization Type set to "Powder", all parameters of Single Crystal block are hidden and not required. + +modQ (\|Q\|): + * If Polarization Type set to "Single Crystal", it is a read-only field. The value is returned from the backend after all Single crystal parameters are filled in. + * If Polarization Type set to "Powder", user can fill the value in. + +Delta E - Ei: + * If and only if Delta E<=Ei, the Delta E value is valid + + +Validation +---------- + +Regarding validation, if all fields are valid, then the front end triggers the backend to send the current parameters and receive the new data and plot the graph. + + +Front end side validation can include: + * required fields + * field types + * threshold limits: Ei, P, deltaE and crystal parameters; qt validators can be used + + +Backend side validation can include: + * qmod calculation + * graph data calculations diff --git a/docs/source/design/polarizationmodel.rst b/docs/source/design/polarizationmodel.rst new file mode 100644 index 0000000..34cdfcd --- /dev/null +++ b/docs/source/design/polarizationmodel.rst @@ -0,0 +1,134 @@ +.. _polmodel: + +Design +======= + + + +PPT Model +------------------- + +.. mermaid:: + + classDiagram + PPTModel <|-- SingleCrystalModel + PPTModel <|-- PowderModel + + + class PPTModel{ + <> + +Double incident_energy_e + +Double detector_tank_angle_s + +Double polarization_direction_angle_p + +Double delta_e + +Double mod_q + +Option graph_type + +calculate_graph_data() + + } + + class SingleCrystalModel{ + +Double single_crystal_a + +Double single_crystal_b + +Double single_crystal_c + +Double single_crystal_alpha + +Double single_crystal_beta + +Double single_crystal_gamma + +String single_crystal_h + +String single_crystal_k + +String single_crystal_l + +calculate_qmod() + } + + class PowderModel{ + <> + } + + + +PPT View +------------------- + +.. mermaid:: + + classDiagram + PPTWindow "1" -->"1" SingleCrystalParameters + + class PPTWindow{ + -Signal~str~:error_message_signal + -Signal~str~:update + + +QLabel:ei_display + +QLineEdit:ei_value + +QLabel:s2_display + +QLineEdit:s2_value + +QLabel:p_display + +QLineEdit:p_value + +QLabel:pol_type_display + +QRadioButton:pol_type_value + +QLabel:delta_e_display + +QLineEdit:delta_e_value + +QLabel:qmod_display + +QLineEdit:qmod_value + +QLabel:graph_type_display + +QComboBox:graph_type_value + +SingleCrystalParameters:single_crystal_parameters + +PlotFigure:plot + +QButton:help_btn + +send_error_message() + -show_error_message() + //+QStatusBar:status_bar + +update_plot() + +show_hide_cystal_parameters() + +validate_delta_ei() + } + + + class SingleCrystalParameters{ + -Signal~str~:update + +QLabel:a_display + +QLineEdit:a_value + +QLabel:b_display + +QLineEdit:b_value + +QLabel:c_display + +QLineEdit:c_value + +QLabel:alpha_display + +QLineEdit:alpha_value + +QLabel:beta_display + +QLineEdit:beta_value + +QLabel:gamma_display + +QLineEdit:gamma_value + +QLabel:h_display + +QLineEdit:h_value + +QLabel:k_display + +QLineEdit:k_value + +QLabel:l_display + +QLineEdit:l_value + +update_qmod() + +send_parameters() + } + + +PPT Presenter +----------------------- + +.. mermaid:: + + classDiagram + PPTPresenter "1" -->"1" PPTModel + PPTPresenter "1" -->"1" PPTWindow + + class PPTPresenter{ + -PPTModel:model + -PPTWindow:view + +update_plot() + +update_qmod() + } + + class PPTModel{ + + } + + class PPTWindow{ + + } diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..8d204a6 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,18 @@ +.. Purpose: The root document of the project, which serves as welcome page and contains the root +.. of the "table of contents tree" (or toctree). + +Hyspecplanningtools +======================= + + +.. note:: + + This project is under active development. + +Contents +-------- + +.. toctree:: + :maxdepth: 1 + + design/index