Comprehensive user guide rewrites/updates

[ntoll]

SOME OF THE EXAMPLES WON'T WORK because they target 2026.1.1 (which is yet to be released).

This PR is stacked on the work done to automatically generate API docs from our source code. It must only be merged after the next release of PyScript, since it documents and makes use of some of the breaking (pyscript.web related) changes.

This PR involves:

• Restructuring the documentation into more logical sections.
• Simplifying the structure so duplications and complex cross-references are (to the best of our ability) removed.
• Checking the content for accuracy.
• Updating the language to make it simpler, better organised and easier to understand.
• Adding example apps based on specific PyScript features.
• Removal of the old PSDC based example apps.
• In the user guide, always having a "what's next" section at the end of a page so folks have somewhere to go.
• In the user guide, embedding the example apps in appropriate places.

TODO:

• Check again the example apps.
• Ensure example app information is coherent.
• Check FAQ.

FEEDBACK WELCOME

[ntoll]

OK. I've done the final corrections and checks. Ready for review.

NOTE The examples do not work as is because version 2026.1.1 has not (yet) been released. When this happens, it'll all work. 👍

[WebReflection]

I need to be honest: there is no way I can properly review all of this until it's published, transformed and whatnot but as I trust you tested everything locally, and because this will not break, strictly speaking, our users' code or projects, as it's about documentation and not library logic, I think the best way forward is to approve and refine anything we think should be refined as a separate (one or more) PRs.

The alternative is to split this MR into dozen different MRs, one per each example + one per docs changes (or each page) but I don't think it's worth it ... what do you think? I let this be your call, hopefully this approach is reasonable to you.

[ntoll]

@WebReflection yeah - this is a difficult one. It's an all-or-nothing type change that relates to a specific version of PyScript.

I agree though - to the best of my ability I've checked (and double checked). Obviously, we're all human and mistakes will get through but we can fix them and refine as/when we notice them.

Next steps:

• We agree the next release of PyScript (next week? I have meetings all afternoon today.).
• I stack a branch for updating the docs to 2026.1.1 on top of THIS branch, so all the references to version numbers get updated.
• I check this branch against the new release (especially the examples).
• By merging the stacked branch, all the other work gets merged too.
• It's done!

Sound like a plan?

[WebReflection]

works for me ... specially the part we update all the things on each released version, which is the most important bit.

out of curiosity: why some example needs/uses 2026.1.1, if I might ask?

[ntoll]

@WebReflection it's the new my_element = page["#some-element-id"] change (it used to be page.find("#some-element-id")[0]), folks have been asking for a direct way to get something by ID for ages, and these examples use it (which is missing in 2025.11.2. 👍