From 95107c4bed6e39225fe64d8f0972160a1008d57e Mon Sep 17 00:00:00 2001 From: dennisbrookner Date: Wed, 8 Nov 2023 14:17:29 -0500 Subject: [PATCH 1/4] reorder pages; add placeholder tutorial page --- docs/index.rst | 3 ++- docs/tutorial.md | 4 ++++ 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 docs/tutorial.md diff --git a/docs/index.rst b/docs/index.rst index 267dc5c..2207c6d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,11 +7,12 @@ Contents .. toctree:: :maxdepth: 2 + Command-Line Reference + Tutorial Contributions & Help License Authors Changelog - Command-Line Reference Full API Reference diff --git a/docs/tutorial.md b/docs/tutorial.md new file mode 100644 index 0000000..2eb1351 --- /dev/null +++ b/docs/tutorial.md @@ -0,0 +1,4 @@ +# Tutorial + +Coming soon! This page will contain a walkthrough of how you might use `laue-dials` on your favorite polychromatic crystallography dataset. + From dcc60f3dd01ba155c1c6c7ab664d49f558da6464 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 8 Nov 2023 19:19:19 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/tutorial.md | 1 - src/laue_dials/__init__.py | 6 ++---- src/laue_dials/algorithms/laue.py | 5 +++-- src/laue_dials/command_line/index.py | 6 ++---- src/laue_dials/command_line/integrate.py | 3 +-- src/laue_dials/command_line/optimize_indexing.py | 3 +-- src/laue_dials/command_line/plot_wavelengths.py | 3 +-- src/laue_dials/command_line/predict.py | 3 +-- src/laue_dials/command_line/refine.py | 7 +++++-- src/laue_dials/command_line/sequence_to_stills.py | 3 +-- 10 files changed, 17 insertions(+), 23 deletions(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index 2eb1351..1f5cf58 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -1,4 +1,3 @@ # Tutorial Coming soon! This page will contain a walkthrough of how you might use `laue-dials` on your favorite polychromatic crystallography dataset. - diff --git a/src/laue_dials/__init__.py b/src/laue_dials/__init__.py index 5e28345..e451f10 100644 --- a/src/laue_dials/__init__.py +++ b/src/laue_dials/__init__.py @@ -2,11 +2,9 @@ if sys.version_info[:2] >= (3, 8): # TODO: Import directly (no need for conditional) when `python_requires = >= 3.8` - from importlib.metadata import (PackageNotFoundError, # pragma: no cover - version) + from importlib.metadata import PackageNotFoundError, version # pragma: no cover else: - from importlib_metadata import (PackageNotFoundError, # pragma: no cover - version) + from importlib_metadata import PackageNotFoundError, version # pragma: no cover try: # Change here if project is renamed and does not equal the package name diff --git a/src/laue_dials/algorithms/laue.py b/src/laue_dials/algorithms/laue.py index 491eccf..7b989d1 100644 --- a/src/laue_dials/algorithms/laue.py +++ b/src/laue_dials/algorithms/laue.py @@ -100,8 +100,9 @@ def gen_beam_models(expts, refls): # Imports from copy import deepcopy - from dials.algorithms.refinement.prediction.managed_predictors import \ - ExperimentsPredictorFactory + from dials.algorithms.refinement.prediction.managed_predictors import ( + ExperimentsPredictorFactory, + ) # Instantiate new ExperimentList/reflection_table new_expts = ExperimentList() diff --git a/src/laue_dials/command_line/index.py b/src/laue_dials/command_line/index.py index 70741df..e36f80a 100644 --- a/src/laue_dials/command_line/index.py +++ b/src/laue_dials/command_line/index.py @@ -8,11 +8,9 @@ import libtbx.phil from dials.util import show_mail_handle_errors -from dials.util.options import (ArgumentParser, - reflections_and_experiments_from_files) +from dials.util.options import ArgumentParser, reflections_and_experiments_from_files -from laue_dials.algorithms.monochromatic import (initial_index, - scan_varying_refine) +from laue_dials.algorithms.monochromatic import initial_index, scan_varying_refine logger = logging.getLogger("laue-dials.command_line.index") diff --git a/src/laue_dials/command_line/integrate.py b/src/laue_dials/command_line/integrate.py index 0ef9e6c..3886dd3 100644 --- a/src/laue_dials/command_line/integrate.py +++ b/src/laue_dials/command_line/integrate.py @@ -17,8 +17,7 @@ from cctbx import sgtbx from dials.array_family import flex from dials.util import show_mail_handle_errors -from dials.util.options import (ArgumentParser, - reflections_and_experiments_from_files) +from dials.util.options import ArgumentParser, reflections_and_experiments_from_files from laue_dials.algorithms.integration import SegmentedImage diff --git a/src/laue_dials/command_line/optimize_indexing.py b/src/laue_dials/command_line/optimize_indexing.py index 6e2fc96..bf7cdf9 100644 --- a/src/laue_dials/command_line/optimize_indexing.py +++ b/src/laue_dials/command_line/optimize_indexing.py @@ -13,8 +13,7 @@ import numpy as np from dials.array_family.flex import reflection_table from dials.util import show_mail_handle_errors -from dials.util.options import (ArgumentParser, - reflections_and_experiments_from_files) +from dials.util.options import ArgumentParser, reflections_and_experiments_from_files from dxtbx.model import ExperimentList logger = logging.getLogger("laue-dials.command_line.optimize_indexing") diff --git a/src/laue_dials/command_line/plot_wavelengths.py b/src/laue_dials/command_line/plot_wavelengths.py index fa3be19..49fac8a 100644 --- a/src/laue_dials/command_line/plot_wavelengths.py +++ b/src/laue_dials/command_line/plot_wavelengths.py @@ -8,8 +8,7 @@ import libtbx.phil from dials.util import show_mail_handle_errors -from dials.util.options import (ArgumentParser, - reflections_and_experiments_from_files) +from dials.util.options import ArgumentParser, reflections_and_experiments_from_files from matplotlib import pyplot as plt logger = logging.getLogger("laue-dials.command_line.plot_wavelengths") diff --git a/src/laue_dials/command_line/predict.py b/src/laue_dials/command_line/predict.py index a8e132f..e65c511 100644 --- a/src/laue_dials/command_line/predict.py +++ b/src/laue_dials/command_line/predict.py @@ -16,8 +16,7 @@ from dials.array_family import flex from dials.array_family.flex import reflection_table from dials.util import show_mail_handle_errors -from dials.util.options import (ArgumentParser, - reflections_and_experiments_from_files) +from dials.util.options import ArgumentParser, reflections_and_experiments_from_files from dxtbx.model import ExperimentList from laue_dials.algorithms.outliers import gen_kde diff --git a/src/laue_dials/command_line/refine.py b/src/laue_dials/command_line/refine.py index d1a5f5f..cae01bf 100644 --- a/src/laue_dials/command_line/refine.py +++ b/src/laue_dials/command_line/refine.py @@ -19,8 +19,11 @@ from dxtbx.model import ExperimentList from dxtbx.model.experiment_list import ExperimentListFactory -from laue_dials.algorithms.laue import (gen_beam_models, remove_beam_models, - store_wavelengths) +from laue_dials.algorithms.laue import ( + gen_beam_models, + remove_beam_models, + store_wavelengths, +) logger = logging.getLogger("laue-dials.command_line.refine") diff --git a/src/laue_dials/command_line/sequence_to_stills.py b/src/laue_dials/command_line/sequence_to_stills.py index cbce992..34c090a 100644 --- a/src/laue_dials/command_line/sequence_to_stills.py +++ b/src/laue_dials/command_line/sequence_to_stills.py @@ -14,8 +14,7 @@ from dials.array_family import flex from dials.array_family.flex import reflection_table from dials.util import show_mail_handle_errors -from dials.util.options import (ArgumentParser, - reflections_and_experiments_from_files) +from dials.util.options import ArgumentParser, reflections_and_experiments_from_files from dxtbx.model import MosaicCrystalSauter2014 from dxtbx.model.experiment_list import Experiment, ExperimentList from libtbx.phil import parse From 2f1656408c45b044ba255e6264f3c2c5b6822a93 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" Date: Wed, 8 Nov 2023 19:19:43 +0000 Subject: [PATCH 3/4] Commit formatting and linting fixes --- src/laue_dials/__init__.py | 6 ++++-- src/laue_dials/algorithms/laue.py | 5 ++--- src/laue_dials/command_line/index.py | 6 ++++-- src/laue_dials/command_line/integrate.py | 3 ++- src/laue_dials/command_line/optimize_indexing.py | 3 ++- src/laue_dials/command_line/plot_wavelengths.py | 3 ++- src/laue_dials/command_line/predict.py | 3 ++- src/laue_dials/command_line/refine.py | 7 ++----- src/laue_dials/command_line/sequence_to_stills.py | 3 ++- 9 files changed, 22 insertions(+), 17 deletions(-) diff --git a/src/laue_dials/__init__.py b/src/laue_dials/__init__.py index e451f10..5e28345 100644 --- a/src/laue_dials/__init__.py +++ b/src/laue_dials/__init__.py @@ -2,9 +2,11 @@ if sys.version_info[:2] >= (3, 8): # TODO: Import directly (no need for conditional) when `python_requires = >= 3.8` - from importlib.metadata import PackageNotFoundError, version # pragma: no cover + from importlib.metadata import (PackageNotFoundError, # pragma: no cover + version) else: - from importlib_metadata import PackageNotFoundError, version # pragma: no cover + from importlib_metadata import (PackageNotFoundError, # pragma: no cover + version) try: # Change here if project is renamed and does not equal the package name diff --git a/src/laue_dials/algorithms/laue.py b/src/laue_dials/algorithms/laue.py index 7b989d1..491eccf 100644 --- a/src/laue_dials/algorithms/laue.py +++ b/src/laue_dials/algorithms/laue.py @@ -100,9 +100,8 @@ def gen_beam_models(expts, refls): # Imports from copy import deepcopy - from dials.algorithms.refinement.prediction.managed_predictors import ( - ExperimentsPredictorFactory, - ) + from dials.algorithms.refinement.prediction.managed_predictors import \ + ExperimentsPredictorFactory # Instantiate new ExperimentList/reflection_table new_expts = ExperimentList() diff --git a/src/laue_dials/command_line/index.py b/src/laue_dials/command_line/index.py index e36f80a..70741df 100644 --- a/src/laue_dials/command_line/index.py +++ b/src/laue_dials/command_line/index.py @@ -8,9 +8,11 @@ import libtbx.phil from dials.util import show_mail_handle_errors -from dials.util.options import ArgumentParser, reflections_and_experiments_from_files +from dials.util.options import (ArgumentParser, + reflections_and_experiments_from_files) -from laue_dials.algorithms.monochromatic import initial_index, scan_varying_refine +from laue_dials.algorithms.monochromatic import (initial_index, + scan_varying_refine) logger = logging.getLogger("laue-dials.command_line.index") diff --git a/src/laue_dials/command_line/integrate.py b/src/laue_dials/command_line/integrate.py index 3886dd3..0ef9e6c 100644 --- a/src/laue_dials/command_line/integrate.py +++ b/src/laue_dials/command_line/integrate.py @@ -17,7 +17,8 @@ from cctbx import sgtbx from dials.array_family import flex from dials.util import show_mail_handle_errors -from dials.util.options import ArgumentParser, reflections_and_experiments_from_files +from dials.util.options import (ArgumentParser, + reflections_and_experiments_from_files) from laue_dials.algorithms.integration import SegmentedImage diff --git a/src/laue_dials/command_line/optimize_indexing.py b/src/laue_dials/command_line/optimize_indexing.py index bf7cdf9..6e2fc96 100644 --- a/src/laue_dials/command_line/optimize_indexing.py +++ b/src/laue_dials/command_line/optimize_indexing.py @@ -13,7 +13,8 @@ import numpy as np from dials.array_family.flex import reflection_table from dials.util import show_mail_handle_errors -from dials.util.options import ArgumentParser, reflections_and_experiments_from_files +from dials.util.options import (ArgumentParser, + reflections_and_experiments_from_files) from dxtbx.model import ExperimentList logger = logging.getLogger("laue-dials.command_line.optimize_indexing") diff --git a/src/laue_dials/command_line/plot_wavelengths.py b/src/laue_dials/command_line/plot_wavelengths.py index 49fac8a..fa3be19 100644 --- a/src/laue_dials/command_line/plot_wavelengths.py +++ b/src/laue_dials/command_line/plot_wavelengths.py @@ -8,7 +8,8 @@ import libtbx.phil from dials.util import show_mail_handle_errors -from dials.util.options import ArgumentParser, reflections_and_experiments_from_files +from dials.util.options import (ArgumentParser, + reflections_and_experiments_from_files) from matplotlib import pyplot as plt logger = logging.getLogger("laue-dials.command_line.plot_wavelengths") diff --git a/src/laue_dials/command_line/predict.py b/src/laue_dials/command_line/predict.py index e65c511..a8e132f 100644 --- a/src/laue_dials/command_line/predict.py +++ b/src/laue_dials/command_line/predict.py @@ -16,7 +16,8 @@ from dials.array_family import flex from dials.array_family.flex import reflection_table from dials.util import show_mail_handle_errors -from dials.util.options import ArgumentParser, reflections_and_experiments_from_files +from dials.util.options import (ArgumentParser, + reflections_and_experiments_from_files) from dxtbx.model import ExperimentList from laue_dials.algorithms.outliers import gen_kde diff --git a/src/laue_dials/command_line/refine.py b/src/laue_dials/command_line/refine.py index cae01bf..d1a5f5f 100644 --- a/src/laue_dials/command_line/refine.py +++ b/src/laue_dials/command_line/refine.py @@ -19,11 +19,8 @@ from dxtbx.model import ExperimentList from dxtbx.model.experiment_list import ExperimentListFactory -from laue_dials.algorithms.laue import ( - gen_beam_models, - remove_beam_models, - store_wavelengths, -) +from laue_dials.algorithms.laue import (gen_beam_models, remove_beam_models, + store_wavelengths) logger = logging.getLogger("laue-dials.command_line.refine") diff --git a/src/laue_dials/command_line/sequence_to_stills.py b/src/laue_dials/command_line/sequence_to_stills.py index 34c090a..cbce992 100644 --- a/src/laue_dials/command_line/sequence_to_stills.py +++ b/src/laue_dials/command_line/sequence_to_stills.py @@ -14,7 +14,8 @@ from dials.array_family import flex from dials.array_family.flex import reflection_table from dials.util import show_mail_handle_errors -from dials.util.options import ArgumentParser, reflections_and_experiments_from_files +from dials.util.options import (ArgumentParser, + reflections_and_experiments_from_files) from dxtbx.model import MosaicCrystalSauter2014 from dxtbx.model.experiment_list import Experiment, ExperimentList from libtbx.phil import parse From fc7f785093034a61392534991261dab5e2caa3bb Mon Sep 17 00:00:00 2001 From: Dennis Brookner Date: Tue, 28 Nov 2023 13:08:51 -0500 Subject: [PATCH 4/4] Instructions for updating docs --- CONTRIBUTING.rst | 48 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 487f5d6..9724283 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -34,15 +34,51 @@ by adding missing information and correcting mistakes. ``laue-dials`` documentation uses Sphinx_ as its main documentation compiler. This means that the docs are kept in the same repository as the project code, and that any documentation update is done in the same way was a code contribution. -When working on documentation changes in your local machine, you can -compile them using ``tox`` +When working on documentation changes in your local machine, make sure you have installed the "docs" extension of the package:: - tox -e docs + pip install laue-dials[docs] + +or if, more likely, you've cloned the repo and are installing from your local copy:: + + pip install -e ".[docs]" + +This makes sure that in addition to ``laue-dials``, you've also installed Sphinx and all of the necessary Sphinx extensions to build the docs. + +To build a copy of the docs locally, you can navigate into the ``docs/`` subdirectory and call:: + + make clean + make html + +The ``docs/_build/html/`` directory should now contain ``.html`` files which can be opened in your web browser. + +Adding docs for new command-line functions +------------------------------------------ + +In order for a command-line function to be added to the documention, you must do two things: + +1. Create a file in the ``docs/cli/`` directory called ``{function-name}.rst``. The contents of this file should match the contents of the other ``.rst`` files in this directory, using the new function's name as appropriate. The easiest thing is to just copy one of the existing files and update it. Note that if the ``====`` header underneath ``laue_dials.{function-name}`` isn't the same length as the text, Sphinx might get mad. +2. Add the new function to the table of contents in ``docs/cli/functions.md``. Otherwise, your new page will exist, but there will be no link to it anywhere! + +In order for a new command-line function to be maximally compatible with this documentation format, three things should be true: + +1. The function's ``help_message`` should exist and contain a useful introduction to the function and it's usage. +2. The function's most commonly used parameters should have expert level 0. +3. Any parameters of the function that ever need to be available to the user should have expert level no higher than 2. + +Adding other pages to the docs +------------------------------ + +New pages can be added to the docs by creating new files in the `docs/` directory. Files can be either ``.rst`` (reStructuredText) or ``.md`` (Markdown) formats. Additionally, ``.md`` files can contain chunks of reStructuredText wrapped inside of ``{eval-rst}`` triple braces:: + + ## Markdown heading + Lots of *markdown* code. + + ```{eval-rst} + .. rstcommand:: -and use Python's built-in web server for a preview in your web browser -(``http://localhost:8000``):: + ``` - python3 -m http.server --directory 'docs/_build/html' +Additionally, you must add any new pages to the table of contents listed in ``docs/index.rst``. List your new page as ``Display Name ``, and place it where you'd like it to appear in order in the Table of Contents. Code Contributions