Dev docs build improvements

[wpotrzebowski]

Currently, building documentation from a dev checkout can be done uing the default approach:
pip install -e .
However this approach is rather slow (seems to rebuild the entire package) and not reliable at picking up documentation changes in the local branch.
A slightly better workaround is:
uv pip install -e . --force-reinstall --no-deps
This is faster but still requires to manually remove a subfolder (e.g. in the built docs - tested on Maci) to force a full docs rebuild.

As a developer, I want to quickly test documentation changes from my local dev checkout using a simple command (for example):
python -m sas

Requirements:
Builds the documentation only (without a full reinstall) or it is fast.
Always picks up changes from the current branch and different repostories (sasmodels and sasdata).
Does not require manually deleting folders to trigger a rebuild.

[wpotrzebowski]

And for the record on Mac I had to remove: venv/lib/python3.12/site-packages/sas/docs to pick up latest changes in sasview

[llimeht]

Some benchmarking tests to see what is going on (I used annotate-output to track output and timings; data are from a few replicates and there's 1-2 s jitter from run to run)

In the table below:

• pip = python -m pip install -v -e .
• pip-nbi = python -m pip install -v --no-build-isolation -e .
• uv = uv pip install -v -e .
• uv-nbi = uv pip install -v --no-build-isolation -e .

step	pip	pip-nbi	uv	uv-nbi
install build-requires (wheels already cached)	21 s	-	2 s	-
start build (checking deps, set version etc)	4 s	4 s	4 s	4 s
run sphinx	49 s	50 s	45 s	52 s
finish build process	4 s	5s	8 s	6 s
copy docs and install wheel	5 s	7 s	0 s	0 s

That uv is faster that pip on its own is because the tools are doing the builds in a clean venv and installing the build-requires into that venv... and pip is slow at doing that. By working in the current venv rather than a temporary venv (with --no-build-isolation) this step is eliminated.

The slowest part of the build is always sphinx itself and that's hard to avoid. There's an outside chance that collect_sphinx_sources.py could preserve timestamps on files, only update files if they are changed, only copy across apidoc output if it has changed and that would let sphinx do an incremental build, but there's a lot of 'hope' in that. (no, I can't explain why uv running sphinx would be faster... that makes zero sense to me but is reproducible. I do wonder if it's running a differently optimised Python interpreter there, or something different about introspection of the classes to do type annotations of the docs.)

The item in the requirements list about building the docs only and not doing the rest of the build is probably not something that needs addressing.

If one wants to just build the docs for manual inspection, then hatchling build --hooks-only as I originally suggested in INSTALL.md would work. However, that's not compatible with editable installs so it's fine for looking at the docs in a web browser (which is fine for iterating on them), but no good for looking at them inside sasview.

For the other two items:

• Always picks up changes: can you give a reproducer for this? I can't get it to fail.
• Does not require manually deleting folders to trigger a rebuild. I can't explain this one at all; the clean step in collect_sphinx_sources.py is unchanged in sasview for about a decade and nukes the sources in the source tree; files in the venv shouldn't be used at all. Is there a reliable way to reproduce?

[butlerpd]

To add to this issue, I have spent the better part of a day trying, and failing, to get this to even work properly. Some notes from my windows PC.

• the docs do seem to also exist in the site-packages folder, but running main.py, even from within the .venv of my developer environment pulls the docs from the release build location of c:\Users\username\AppData\Local\sasview\SasView\version. One indeed has to delete THAT folder in order to pick up any changes
• Running pip install -e . from within the sasview directory does build with changes made to docs in the sasview repo, but as @wpotrzebowski says, ONLY from that repo. Changes made in sasmodels seem to be ignored as can be seen by examining the html files in the newly created build directory under docs etc. Also the sphinx docs directory with all the scraped rst files only has old versions of the sasmodels rst but new versions of sasview rst files.
• Running the same pip install in the sasmodels directory does seem to update the html files in the temporary build docs folder but it is not clear how sasview is supposed to pick them up? In any case sasview never did in all my tries.
• I did try once deleting all build directories (and other temp directories I could find) and ran the magic pip install command on sasmodels followed by doing the same on sasview but that also failed to bring the changes into the sasview directory (or be transferred to the folder where main.py picks them up from)

[butlerpd]

@llimeht, regarding deleting folders (that seems to be a universal experience at the camp so far), the problem I think is that running run.py always created a build folder in which the final documentation lived and then the GUI it launched pulled from that when clicking for example Help or Help->documentation etc. Now it seems to be pulling either from the site-packages (which does not seem to be properly updated) or the release location as I just described above.

[llimeht]

To address the confusion about where the sources for the docs and the rendered docs are found, for both the build and at runtime, the documentation is found from whatever the installed module is. Always. This is designed to be simple and not conditional on particulars of local checkouts or different methods of invocation.

• At sasview build time, the installed sasdata and sasmodels packages are inspected for doc sources.
• If one wants to see some changes to sasmodels docs rendered all the way through to the sasview help viewer, then install the updated sasmodels first; but note that you can look at the changes to sasmodels docs inside the sasmodels project without going through the much longer build cycle with sasview.
• At runtime, sasview looks for the docs inside its installed module. If a change hasn't been installed, it hasn't been installed. The location of the located docs is logged, so folks seeing it pick up docs from odd places at runtime should see what is logged and then we can work backwards.
• A pile of the runtime behaviour only got fixed last week when I simplified down the code paths so that we have only one code path to find the docs now; that does mean that out of date branches might do anything (that being the 6.0/6.1 problem). Rebasing old branches to current main would help.
• wrt "site-packages or the release location" - site-packages is the release location; looking at the code, the path that might get to the user directory rather than site-packages is from not having installed sasview (but even that I'm not convinced about). A stale branch is even more likely.
• The two caveats to the above are
  • the mac installer bundle might do some funky things which might cause it to copy the files out to the user directory still. I can't test this.
  • wheel unpackers (pip, uv) might do some unexpected things when updating an already installed package; they know what files they need to update and should do the right thing, and I couldn't spot any problems with this in updating existing files, but there's a chance.

I'm very suspicious about the comment of running __main__.py from inside the venv - that sounds a lot like running with a different python to the one that the venv is using. There's nothing that pins an individual python file to a particular venv, so poking around within the venv is a recipe for unintentionally finding other installations of sasview are on disk and in sys.path. python -m sas where python is the interpreter for the venv is the portable approach (vscode can be taught to do exactly this with a "module": "sas" config in launch.json; other IDEs will be able to do similarly; those working in the commandline need to know what venv they are in and can configure their shell prompt to make that clear.)

run.py doing something different to the installed versions of sasview was the source of a great many bugs in recent sasview releases so yes, all the icky things it did with having sasview attempt to find the docs in one of 4 different locations are all gone and I was grateful when Paul finally called time on it. We will be in a much better place once we get this working well.

To that end, I'd be happy to step through the code with a debugger to see what goes wrong and put mitigations in place as needed, but I need a reproducer to do so. Absolutely every detail of what is (or isn't!) done. The above describes final failure modes and an understandable level of frustration but not the steps that led to the failure, and isn't actionable by me atm.

[butlerpd]

I'm very suspicious about the comment of running __main__.py from inside the venv - that sounds a lot like running with a different python to the one that the venv is using.

For clarification I meant that the .venv created as indicated in install.md was activated for everything I discussed above.

I don't understand what is meant by "installed module." We simply are following the instructions on install.md and then, with the .venv active, choosing the branch via git checkout (i think that is what it is called though I usually use the pycharm IDE to do that). If that is not the version of the module being used then what is?

I understand that there were probably lots of very good technical reasons for replacing run.py, but I have to say that for me, and several others I know, it just worked for our debugging needs. Getting back to that level of utility with the new method would extraordinarily useful. Hopefully this cleanup can in fact make it even more robust and reliable but for now, with the current instructions, it is not that useful I'm afraid.

[llimeht]

don't understand what is meant by "installed module."

If pip install or pip install -e has not been run, it's not installed. Comments above say that has not happened after changes have been made, so that's something that needs to be added to the instructions. We can do that, but we need to know what folks are actually doing ... I can't do this by guesswork.

We can certainly get to the utility and I can help with that, but I need a reproducer.

There's also already work to improve the documentation (#3753), but that work needs fixing to follow up the review comments before it can be merged. If @TLO218 is at codecamp then working side by side to fix it up and get it merged would be good.

[llimeht]

I've spent some time trying to guess where folks are tripping up on this and
https://github.com/SasView/sasview/blob/ca353d81ef8345ab2c03059034b03a9d1975cabc/INSTALL.md#seeing-and-testing-your-changes is ready for merging in #3753.

Guesswork would be better replaced by a detailed reproducer though, so I'll pause work on this until there is one.

[butlerpd]

Thanks Stuart! Your work is much appreciated!

Yes @TL0218 was at contributor camp, but there where a million different things flying around as usual and we sorta moved on from this in order to accomplish things together. I've stayed behind a day but everyone else is gone so we will have to sort this out remotely and over fortnightly calls I guess. Indeed, I think a large part of our problem is communication: tripping up over nomenclatures. Pausing till there is a better description of the use cases and the issues encountered during those sounds like the right thing to me.