docs: revamp documentation#182
Merged
sbillinge merged 3 commits intodiffpy:john-developmentfrom Feb 10, 2026
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## john-development #182 +/- ##
===================================================
Coverage ? 77.50%
===================================================
Files ? 3
Lines ? 40
Branches ? 0
===================================================
Hits ? 31
Misses ? 9
Partials ? 0 🚀 New features to boost your workflow:
|
Contributor
|
I agree that we don't need comprehensive docs initially, so we just need to get this to a point where there are minimal docs explaining how to install and how to get started. The default docs from scikit-package are a good start, unchanged, pointing to installation instructions in the README (so we don't have to maintain them in two places), the basic thing of what the package does (also in the readme, but copy-paste this over) and getting started (what you type to make it run). Later we can add some examples. An example of good docs I think are Caden's in diffpy.cmi, but they are further along.. The docstrings auto-build into the API docs so you don't have to write that (also the default from skpkg) as long as you have written good docstrings. Can you try and do those things and build the docs and paste images in here as it is too much effort during reviewing to actually build the docs. YOu dojn't have to paste every page, just the top level and any key parts you want reviewed. |
Contributor
|
@john-halloran I merged this PR because when I change the URL you will want to blow away your local and reclone. You don't have to, but this can save headaches, and it is cleaner if you don't have any local branches you have to migrate over. |
sbillinge
added a commit
that referenced
this pull request
Feb 19, 2026
* Initial commit of John refactor of SNMF (#140) * added my files * [pre-commit.ci] auto fixes from pre-commit hooks * Updated X and Y optimizers, now produces formatted but partially incorrect output * removed duplicate class * Working build (no normalization) --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> * fix stop condition and add Y/A normalization (#141) Co-authored-by: John Halloran <jhalloran@oxy.edu> * Added x normalization (#143) Co-authored-by: John Halloran <jhalloran@oxy.edu> Co-authored-by: Simon Billinge <sbillinge@users.noreply.github.com> * Loop cleanup and scikit-learn style parameters (#146) * Cleaned up looping behavior and aligned some params with scikit-learn. * Combined quadratic solvers --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * feat: Add random state feature. (#150) * feat: Add random state feature. * Add class docstring * components->n_components * Updated docstring * Shorten and reformat docstring * docstring typo * Flag self.rng as private * Make logic for n_components and Y0 more rigid * added class attributes to docstring * fix: cleaner import of SNMFOptimizer * fix: correct class instantiation after change in import --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> Co-authored-by: Simon Billinge <sbillinge@users.noreply.github.com> * refactor: Remove old tests and source files (#160) Co-authored-by: John Halloran <jhalloran@oxy.edu> * style: convert variables to lowercase (#159) * style: Convert variables to lowercase * chore: Add news item * style: lowercase remaining variables * style: fix indentation on docstrings * style: rename and make public certain attributes * style: update docstring defaults --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * Fixes to class attributes and style (#163) * fix: use symmetric initial phase fractions * style: don't store objective function in a class attribute, just use history --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * Restored functionality to working state (#165) * docs: update docstring and imports * style: remove non-class function from class * fix: using working quadratic solver for weights * fix: restore working MATLAB-like loop functionality --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * feat: add live plotting of updates (#166) * feat: add live plotting of updates * style: make plotting vars lowercase --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * test: add initial test of optimizer (#167) * test: add initial test of optimizer * style: switch to local imports and plural folders * style: add README to sNMF test --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * Replace 1D apply_interpolation with np.interp (#168) * refactor: get residual matrix without a helper * perf: remove unused derivatives from apply_interpolation * chore: remove old residual matrix and reference to derivatives * refactor: replace remaining apply_interpolation with np.interp * style: remove references to old variable names --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * refactor: reconstruct separate from residuals (#169) * refactor: reconstruct separate from residuals * fix: inputs to reconstruct_matrix should not be optional * docs: updated default documentation for init_weights --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * refactor: move optimization out of init and into fit (#170) * style: per sklearn, attributes learned from data end with underscore * refactor: move optimization out of init and into fit * fix: use new fit() for test * style: end fit() with return self * docs: update docstring to reflect new functionality * refactor: use rho and eta in fit * feat: use reset for sequential refinements * fix: use copies for safety --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * refactor: apply_interpolation_matrix() is now compute_stretched_components() (#171) * fix: guard against zero/NaN stretches in apply_interpolation_matrix * refactor: use broadcasting instead of np.tile in apply_interpolation_matrix * refactor: flatten from a single buffer in apply_interpolation_matrix() * refactor: drastically simplify indexing in apply_interpolation_matrix() and remove legacy MATLAB terminology * style: rename apply_interpolation_matrix() to compute_stretched_components() --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * refactor: change get_objective_function into a static method and getter (#174) * refactor: compute objective function in a static method and retrieve via getter * refactor: change get_objective_function into a static method and getter * fix: update location for _tests-on-pr.yml * fix: use expected name for requirements/tests.txt * fix: add cvxpy to requirements/conda.txt * fix: add matplotlib to requirements/conda.txt --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * skpkg: apply black to all files in the project directory (#176) Co-authored-by: John Halloran <jhalloran@oxy.edu> * chore: update package to latest scikit-package version (#178) * chore: update to latest version of scikit-package * chore: restore citation information * fix: restore missing requirements * [pre-commit.ci] auto fixes from pre-commit hooks * fix: restore historical changelog --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> * feat: skip updating stretch if stretching factor is zero (#181) * style: make line length <80 throughout * feat: skip updating stretch() if stretching factor is zero * chore: fix codespell complaint * fix: use correct version of rho * style: clean up several lines and remove noqa --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * docs: revamp documentation (#182) * refactor: move doc to docs and update requirements * docs: remove old tables and recreate getting started page * docs: load documentation from snmf_class.py --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> * refactor: change references of snmf to stretched-nmf (#185) * chore: use new name in scikit-package space * refactor: rename references throughout program snmf -> stretched-nmf * refactor: rename project references * chore: add news item for package-name-update * chore: CI toml issue --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> --------- Co-authored-by: John Halloran <jhalloran@oxy.edu> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Simon Billinge <sbillinge@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
I don't think this PR is anywhere close to done, but since documentation is not my expertise, I've made it a draft in order to get feedback on what needs to be added. I still think rushing a release is a good idea, so this need not be perfect. The basic goal should be that someone unfamiliar with the software has enough information to know how to load their data and run the program.