Overhaul documentation with Diataxis structure and VHS demos#120
Merged
Conversation
jezdez
force-pushed
the
docs-overhaul
branch
5 times, most recently
from
469d016 to
2159d76
Compare
Restructure docs following the Diataxis framework (tutorials, how-to guides, reference, explanation) modeled after conda-workspaces and conda-global. Add VHS terminal demos for quickstart, install, update, remove, reset, and base-protection workflows. Simplify conf.py and trim unused Sphinx extensions. Demos use real operations (not dry-run) with conda-index as the example plugin. Quickstart shows the full lifecycle: check protection, install, update, reset.
Ground the motivation in conda-self's actual history: the evolution from protect to migrate to doctor health checks, the naming decision (self vs base), and the design choices informed by issues #15, #89, and community feedback. Frame conda-self as a plugin that manages conda installations, not just environments.
Link to conda's docs for conda doctor, conda install, conda config, conda info, .condarc configuration, and the plugins developer guide throughout all documentation pages.
Downgrade conda to 26.1.1 in hidden setup so the update demo shows a real 26.1.1 -> 26.3.1 upgrade with package plan output.
Replace the pixi shell-hook approach with a dedicated _setup.sh script that installs a fresh Miniforge + conda-self for each demo recording. This produces cleaner output with realistic paths, avoids pixi env leakage, and enables demos that work correctly (real plugin removal, real base protection fix, etc.).
SpecsCanNotBeRemoved and SpecsAreNotPlugins were passing a raw Python list into the f-string, producing output like "Packages '['conda']'". Join the list into a comma-separated string instead.
Backticks render as literal characters in terminal output. Use single quotes for consistency with conda's own messaging style.
Use --quiet for the base-protection --fix step to avoid dumping the full clone package list. Re-record reset, quickstart, and remove demos to pick up the single-quote and dashlist formatting changes.
The fresh Miniforge ships conda 26.1.1 while conda-forge has 26.3.x, so conda self install would also update conda alongside the plugin. Update conda in the hidden setup so the visible install step only shows the plugin being added.
- Exception messages now handle singular/plural correctly and use comma-separated lists instead of dashlist for readability - Remove "SUCCESS!" from reset messages to match conda's understated tone - Guard non-conda package warning with --quiet flag in base-protection fix
Remove leading spaces and use single quotes instead of backticks for the 'conda doctor --fix' suggestion message.
Picks up: exception renames (PluginRemoveError, NotAPluginError), installer snapshot preservation (no mamba/pip removal), removed SUCCESS! from reset, fixed indentation in base-protection message, single quotes in user-facing messages.
- Drop update step from quickstart (dedicated demo covers it) - Use raw conda install for older conda-index in update demo to avoid version pinning in history - Re-record both demos
- reset, quickstart: now show `installer-provided (with updates)` snapshot message - base-protection: uses the new installer-updated strategy in the fix step; tighten comment to drop "to essentials" (installer-provided packages are preserved) - remove: add a `--force --dry-run` follow-up to showcase the override, and reword the comment since permanent packages are now protected rather than unremovable
The WHAT_TO_EXPECT preamble on `conda self reset` claimed the command would reset base to only conda, its plugins, and their dependencies -- but since the installer-updated snapshot became the default (#122), the reset also preserves installer-provided packages. The demos surfaced the contradiction between this preamble and the trailing "installer-provided (with updates) snapshot" success line. - Split WHAT_TO_EXPECT into snapshot/essentials variants and print the right one after snapshot resolution - Update the matching prose in docs/features.md and docs/quickstart.md - Reword the reset/quickstart tape comments to "installer-provided snapshot" - Re-record reset, quickstart, and base-protection demos
marcoesters
reviewed
May 4, 2026
conda-self is not bundled with conda. Replace the "included by default" prerequisite lines with an explicit install instruction.
marcoesters
approved these changes
May 4, 2026
Contributor
marcoesters
left a comment
marcoesters
left a comment
There was a problem hiding this comment.
I don't know much about the .tape format, so I can't judge those files. However, the GIFs look good to me, so any optimization can be done in follow-up PRs.
The pybind11-abi==11 variant of libmambapy 2.6.0 on win-64 fails to load its native bindings extension, breaking all Windows conda-forge test jobs. Pin to <2.6 until the upstream build is fixed. See conda-forge/mamba-feedstock#384.
The install spec constraint is only used during env creation. Without a conda-meta/pinned file, `conda self update --yes` freely upgrades libmambapy to 2.6.0 which breaks on Windows (DLL load failure). See conda-forge/mamba-feedstock#384.
This test creates its own environment via tmp_env (not the session fixture), so the session-level pin has no effect. Add both the install spec and conda-meta/pinned to prevent the solver upgrading libmambapy to 2.6.0 during `conda self update`. See conda-forge/mamba-feedstock#384.
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.
Summary
Documentation
conf.pyto use only essential Sphinx extensions (myst-parser, sphinx-design, sphinx-copybutton)pyproject.toml(sphinx-reredirects, sphinx-sitemap, sphinxcontrib-programoutput, linkify-it-py)robots.txtVHS demos
pixi run demostask for recording demo GIFsdemos/_setup.sh) instead of the pixi dev env, so the rendered paths and plugin operations are realisticmainto pick up Split--snapshot installerintoinstaller-exactandinstaller-updated#122 (installer-updated snapshot is now the default reset target) and Add--forceflag toconda self remove#133 (conda self remove --force)Code changes surfaced while recording demos
Several user-facing rough edges became obvious once the terminal output was being captured as a GIF. Fixed them here rather than in follow-up PRs:
conda_self/exceptions.py—SpecsCanNotBeRemoved/SpecsAreNotPluginsnow render package names as a comma-separated string (previously producedPackages '['conda']'). Singular/plural forms handled correctly.conda_self/health_checks/base_protection.py—conda doctor --fixguards the non-conda-package warning behind--quiet, and the check message uses single quotes and correct indentation around theconda doctor --fixsuggestion.conda_self/cli/main_reset.py— splitWHAT_TO_EXPECTintoWHAT_TO_EXPECT_SNAPSHOT/WHAT_TO_EXPECT_ESSENTIALSand print the right one after snapshot resolution, so the preamble no longer contradicts the trailinginstaller-provided (with updates) snapshotsuccess line introduced by Split--snapshot installerintoinstaller-exactandinstaller-updated#122. Matching prose indocs/features.mdanddocs/quickstart.mdupdated.Documentation structure
Test plan
pixi run -e docs docsbuilds with zero warningsmainincluding Split--snapshot installerintoinstaller-exactandinstaller-updated#122 (installer-updated reset default) and Add--forceflag toconda self remove#133 (--force)