Update install instructions, Readme, and add resources

INSTALL.md

@@ -1,6 +1,6 @@
 # Quick Intro for Building SasView
 
-Note - at the current time SasView will only run in gui form under Python 3.12 and later.
+:warning: Note - at the current time SasView requires Python 3.12 or Python 3.13.
 
 Whether you're installing SasView to use as a tool for your research or
 because you're wanting to work on the code, it is recommended that you
@@ -12,39 +12,48 @@ A `venv` or a `conda` are both popular choices.
 Installers for SasView can be found at [https://www.sasview.org/](https://www.sasview.org/),
 for various operating systems. You will also find walk through tutorials on how to install and use SasView.
 
-You can also install SasView using standard Python installation tools,
-such as `pipx install sasview` to install it into its own standalone
-environment (or `pip install sasview` to install it into your current Python environment).
-
+You can also install SasView using standard Python installation tools, such as
+- `uv tool install sasview` (or `pipx install sasview`) to install it into its own standalone
+environment
+- or `uv pip install sasview` (or `pip install sasview`) to install it into your current Python environment.
 
 ## Making a SasView Development Environment
 
 If you're familiar with working with developing in Python, then the very quick version is:
 
 ```shell
+# clone the repository
 git clone https://github.com/sasview/sasdata/
 git clone https://github.com/sasview/sasmodels/
 git clone https://github.com/sasview/sasview/
+
 cd sasview
-python -m venv venv
-# venv\Scripts\activate & REM Windows: activate environment
-. venv/bin/activate  # Linux/Mac: activate environment
-pip install -e ../sasdata
-pip install -e ../sasmodels
-pip install -e .[dev,test]
+
+# create the virtual environment
+python -m venv .venv
+# .venv\Scripts\activate & REM Windows: activate environment
+. .venv/bin/activate  # Linux/Mac: activate environment
+
+# install repositories in editable/developer mode in the venv
+# use "python -m ..." to ensure the venv's pip is used
+python -m pip install -e ../sasdata
+python -m pip install -e ../sasmodels
+python -m pip install -e .[dev,test]
+
+# test if sasview launches
 python -m sas
 ```
 
 Step by step, that is:
 
- 1. Obtain the SasView source using `git`. You will likely need to coordinate
+1.  Obtain the SasView source using `git`. You will likely need to coordinate
     updates to `sasdata` and `sasmodels`. The
-    `bumps` (https://github.com/bumps/bumps) and
-    `periodictable` (https://github.com/python-periodictable/periodictable)
+    [`bumps`](https://github.com/bumps/bumps) and
+    [`periodictable`](https://github.com/python-periodictable/periodictable)
     packages are far more loosely coupled, but depending on what you are
     doing you may also want them as development packages.
- 1. Create a Python virtual environment in the `venv` directory.
- 1. Activate the `venv` so that Python and its modules from the venv are used.
+1.  Create a Python virtual environment in the `.venv` directory.
+1.  Activate the `.venv` so that Python and its modules from the venv are used.
     Note that the particular syntax above works for the `bash` and `zsh` shells under Linux, Windows and macOS;
     if you use `cmd` or PowerShell under windows, there are
     [different ways](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments)
@@ -53,7 +62,7 @@ Step by step, that is:
     It will take a while to download and unpack all the dependencies.
     The `pip install -e` command says to install the package in development mode
     so that any changes you make in the source tree will be available the
-    next time you run the program. The `.[dev,test]` syntax says to install
+    next time you run the program. We execute this using the `python -m` syntax in order to ensure that the virtual environment python is used. The `.[dev,test]` syntax says to install
     the current directory (sasview) with test and dev dependencies.
  1. Run SasView! As an alternative to typing `python -m sas`, you can simply type `sasview`.
 
@@ -65,8 +74,8 @@ dependencies should be a one-off task.
 When you want to work on SasView again at a later date, you can type:
 
 ```shell
-# venv\Scripts\activate  & REM Windows: activate environment
-. venv/bin/activate  # Linux/Mac: activate environment
+# .venv\Scripts\activate  & REM Windows: activate environment
+. .venv/bin/activate  # Linux/Mac: activate environment
 python -m sas
 ```
 
@@ -76,11 +85,95 @@ Note that many Python-focused integrated development environment programs have t
 ability to activate the venv for you as part of the process of starting and
 debugging software, e.g.:
 
- - [VS Code](https://code.visualstudio.com/docs/python/environments)
- - [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html)
+- [VS Code](https://code.visualstudio.com/docs/python/environments)
+- [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html)
+
+## Seeing and testing your changes
+
+Having set up the venv for your work, it's important that you activate the venv and run sasview inside it.
+When you're working across several different sets of changes, you might end up with multiple different venvs.
+
+The instructions above used *editable* installs (that is `-e` for pip) which means that any changes to Python code and resources that live inside the Python module next to Python files (like icons) will take effect from when you next start SasView. This will be true for all the projects that you installed as editable installs in setting up your development environment.
+
+
+### Resources that are created or moved during the build
+
+For files that do not live in git in the same place as the module expects to find them, the magic of editable installs does not work, likewise for files that are generated as part of the build process.
+
+**GUI — automated**: For `.ui` files that are part of the SasView GUI, new Python files are automatically regenerated by sasview if needed so there's nothing manual you need to do.
+Running `uic` to make the user interface is fast enough that it can be done on the fly so we can get away with this.
+
+**Documentation and other resources ­— manual steps required**: running sphinx is not fast, and so Python will need some help from you for the documentation and some other files that do not live in git in the same place as they do in the installed Python module.
+Specifically *editable* install magic does not apply to:
+
+- files that are listed in `pyproject.toml` in the `force-includes` blocks:
+
+   - `example_data`
+   - `src/sas/sasview/media/`
+
+- all sphinx documentation files; the source for the documentation is assembled by `collect_sphinx_sources.py` from files scattered across multiple projects. The documentation is then built by sphinx and the output needs to be installed. In particular, the following need manual handling in the editable installation:
+
+  - `.rst` files
+  - auto-generated documentation files from apidoc
+  - auto-generated model descriptions and sample output
+  - images that are copied into the documentation (often from `media` directories in the case of SasView)
+
+To have changes to any of these file propagate into the build, the module needs to be reinstalled: `python -m pip install -e .`
+The process of reinstalling the module rebuilds the documentation and copies it into `site-packages`, so that it can be used. Since all the dependencies are already installed, the build just runs the sphinx tools with the correct options and copies the output.
+
+:warning: changing the file doesn't just mean opening it in your editor; switching the git branch will also change the file behind Python's back and you need to follow the same instructions below to see the changes.
+
+:warning: building sasview will use whatever sasdata and sasmodels packages are installed into the current venv; if you're looking at the wrong venv or haven't *installed* changes to other packages into that venv, they aren't visible.
+
+To be explicit:
+
+- **sasmodels:** you change model files or documentation in `sasmodels`
+
+  - if you just want to see what that looks like to check your syntax etc, then
+    1. inside your sasmodels directory: `python -m pip install --no-build-isolation -e .`
+    2. look at the documentation in your browser (`build/doc/index.html`)
+
+  - if you want to see what that looks like inside SasView,
+
+    1. inside your sasmodels directory: `python -m pip install --no-build-isolation -e .` ( :warning: this is a new(ish) step and will generated puzzling results if forgotten)
+    2. inside your sasview directory: `python -m pip install --no-build-isolation -e .`
+    3. start SasView and look at the help
+
+- **sasdata:** you change documentation in `sasdata`
+
+  - same as for sasmodels, above
+
+- **sasview:** you change documentation in `sasview`
+
+   1. inside your sasview directory: `python -m pip install --no-build-isolation -e .`
+   2. look at the documentation in your browser (`build/doc/index.html`)
+   3. start SasView and look at the help
+
+
+
+If you intend to repeat this many many times, you can speed it up:
+
+- `--no-build-isolation` as shown above builds without creating a new temporary venv
+- set `SASMODELS_BUILD_CACHE` in your environment so sasmodels will cache the figures from sasmodels, e.g. `export SASMODELS_BUILD_CACHE=~/.cache/sasmodels-figures`. (You need to empty the cache yourself from time to time; see [the documentation inside sasmodels](https://github.com/SasView/sasmodels/blob/master/doc/genmodel.py#L9) for details, suggestions and other caveats.)
+- fundamentally, the slow part is always (and always was) running sphinx to render the documentation
+
+
+### Details of editable installs (for those who want to know)
+
+When `pip` does an *editable* install, it does 3 things
+that you will be able to see in your venv's site-packages (e.g. `.venv/lib/python3.X/site-packages/`):
+
+- adds the `sasview-X.Y.Z.dist-info` metadata directory that tells Python that the module is installed, along with details like its version, dependencies, file manifest
+- places a `_sasview.pth` file that tells the import machinery where to find the module code and embedded resources; this will point to the `src` directory inside your sasview git clone.
+- creates a `sas` directory that contains only the files that don't live in the "right" place in git and therefore do not sit in the filesystem in the correct location for the editable install.
+
+(For a regular installation rather than an editable installation, the `.pth` file would not exist and all the module files would be in that `sas` directory.)
+
+
+## More information
 
 More information can be found at:
 
- - http://www.sasview.org/help
- - http://www.sasview.org/faq
- - https://github.com/SasView/sasview/wiki/DevNotes
+- [http://www.sasview.org/help](http://www.sasview.org/help)
+- [http://www.sasview.org/faq](http://www.sasview.org/faq)
+- [https://github.com/SasView/sasview/wiki/DevNotes](https://github.com/SasView/sasview/wiki/DevNotes)

README.md

@@ -1,7 +1,170 @@
-[SasView](http://www.sasview.org) is a Small Angle Scattering (SAS) analysis package for the analysis of 1D and 2D scattering data directly in inverse space. The focus was originally on neutron data (SANS) but has been used for X-ray’s as well and includes a tool for determining a slit resolution for the SAXSess instrument. SansView also includes PrView to invert SAS data to P(r), a resolution calculator, and a scattering length density calculator among others tools. A simple plugin mechanism is available for users to add custom models. 
+![Logo](https://github.com/SasView/sasview.github.io/blob/master/img/sasview_logo.png)
 
-This project was initiated by the NSF funded DANSE project, DMR-0520547, SANS sub-project at the University of Tennessee Knoxville. Acknowledgement of that original funding would be appreciated in any publications that make use of the software.
+<div align='center'>
+    <a href="https://github.com/SasView/sasview/releases/latest"><img src="https://img.shields.io/github/v/release/SasView/sasview" alt="Latest Release" /></a>
+    <a href="https://github.com/SasView/sasview/commits/main"><img src="https://img.shields.io/github/last-commit/SasView/sasview" alt="Last Commit" /></a>
+    <a href="https://sasview.org"><img src="https://img.shields.io/website-up-down-green-red/http/sasview.org.svg" alt="Website Status" /></a>
+    <a href="https://opensource.org/licenses/bsd-3-clause"><img src="https://img.shields.io/badge/License-BSD-brightgreen" alt="License"></a>
+</div>
 
-This project receives funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 654000
+---
+
+# General
+
+[SasView](http://www.sasview.org) is a Small Angle Scattering (SAS) analysis package for the analysis of 1D and 2D scattering data directly in inverse space.
+The focus was originally on neutron data (SANS) but has been used for X-rays as well and includes a tool for determining a slit resolution for the SAXSess instrument.
+SasView also includes PrView to invert SAS data to P(r), a resolution calculator, and a scattering length density calculator among others tools.
+A simple plugin mechanism is available for users to add custom models.
+
+# Acknowledgement
+
+This project was initiated by the NSF-funded DANSE project, DMR-0520547, a SANS sub-project at the University of Tennessee. Acknowledgement of that original funding would be appreciated in any publications that make use of the software.
+
+This project received funding from the European Union’s Horizon 2020 research and innovation programme under the SINE2020 project, grant agreement No 654000.
 
 [SasView website](http://www.sasview.org)
+
+The latest stable releases of SasView can be found on the website.
+The following instructions will focus on providing materials for scripting, developing and would lead you to the most important resources.
+
+# Install instructions
+
+## Users
+
+Users can install SasView either from the installers listed on the [SasView website](http://www.sasview.org),
+or directly from the packages distributed by `pip`.
+
+### Install using `pip` inside a virtual environment in the current directory:
+
+
+```shell
+python -m venv .venv # create the environment
+. .venv/bin/activate # activate the environment on linux and MacOS
+# .venv\Scripts\activate & REM Windows: activate environment
+
+python -m pip install sasview
+
+python -m sas   # launch the gui
+```
+
+### Install using `uv` for your user:
+
+```shell
+uv tool install sasview
+
+uvx sasview   # launch the gui
+```
+
+**Note:** To launch SasView, it needs to be installed.
+Running SasView from a source directory is not supported.
+
+## Developers
+
+The installation instructions for developers can be found [here](INSTALL.md).
+Installing the development-version of SasView with conda is currently not supported.
+`NOTE:` In case you want to contribute, please also checkout the [DevelopersNotes](https://github.com/SasView/sasview/wiki/DevNotes_DevGuide_GettingStarted).
+
+## Getting Started
+
+### Scripting
+
+This section is a small scripting example in SasView to check your installation.
+We will fit a simple sphere model. For this first lets synthesize input data.
+
+```python
+import numpy as np
+from sasmodels.bumps_model import Model
+from sasmodels.core import load_model
+from sasmodels.direct_model import call_kernel
+
+# define q vector
+q = np.logspace(-3, -0.1, 200)
+
+# define the model
+exp_model = load_model("sphere")
+exp_pars = {
+    "radius": 50,
+    "sld": 1,
+    "sld_solvent": 6,
+    "scale": 1,
+    "background": 0.001,
+}
+
+# calculate intensities
+Iq = call_kernel(exp_model.make_kernel([q]), exp_pars)
+
+# calculate errors and normalize data
+max_counts = 1e7  # approximate number of counts at first q values
+norm = Iq[0] / max_counts
+counts = np.random.poisson((Iq / norm).astype(int))
+errors = np.sqrt(counts) * norm
+data = counts * norm
+dataset = np.array([q, data, errors]).T
+
+# saving the data
+header = (
+    "Neutron-like data generated for model "
+    + exp_model.info.name
+    + " with parameters:\n"
+)
+for key in exp_pars.keys():
+    header += key + " = " + str(exp_pars[key]) + "\n"
+header += "Q\t counts\t error"
+
+np.savetxt("scattering.txt", dataset, fmt="%12.6e", delimiter="\t", header=header)
+```
+
+...and now let's do the fitting. We will optimize the scale, radius and background starting from an inital values close to the ground truth.
+
+```python
+import matplotlib.pyplot as plt
+from sasmodels.bumps_model import Model, Experiment
+from sasmodels.core import load_model
+from sasmodels.data import load_data
+from bumps.fitters import fit
+from bumps.names import FitProblem
+
+# defining the  model to fit
+fit_pars = {
+    "radius": 80,
+    "sld": 1,
+    "sld_solvent": 6,
+    "scale": 0.900,
+    "background": 0.05,
+}
+fit_kernel = load_model("sphere")
+fit_model = Model(fit_kernel, **fit_pars)
+
+## setting fitting ranges
+fit_model.radius.range(10, 1000)
+fit_model.scale.range(1e-3, 10)
+fit_model.background.range(1e-9, 0.1)
+
+# load the data we synthesized above
+exp_data = load_data("scattering.txt")
+
+# Setup the experiments, sharing the same model across all datasets.
+M = Experiment(data=exp_data, model=fit_model, name="MyAwsomeFit")
+
+problem = FitProblem(M)
+
+plt.figure()
+problem.plot(view=True)
+
+# fit the results
+result = fit(problem, method="dream")
+
+print(f"Final chisq {problem.chisq()}\n")
+problem.plot()
+for k, v, dv in zip(problem.labels(), result.x, result.dx):
+    print(f"{k} : {v:.4f} +- {dv:.4f}")
+plt.show()
+```
+
+This simple fit should results in a $\chi^2$ close to one.
+
+![image](./simpleexample.png)
+
+# Resources
+
+In case you are just getting started or you want to contribute please checkout some selected [resources](/RESOURCES.md).