Sphinx Setup Lab: Download, Extraction, WSL/Debian, and Command Basics

Session Overview

  • The session is a hands-on walkthrough for setting up Sphinx in a Windows/WSL (or Mac) environment, handling downloads, extracting archives, navigating the file system, and running installation steps with attention to safety and backups.
  • Emphasis on step-by-step execution, verifying each stage, and avoiding catastrophic mistakes (e.g., wiping a system). The instructor repeatedly compares careful, incremental progress to a safer approach rather than rushing straight to root access.

Prep and Workspace Management

  • Ensure everyone is present and engaged; ask for confirmation if someone isn’t there.
  • Use link-opening techniques to manage multiple resources (e.g., Ctrl-click to open in a new tab).
  • Open the Downloads folder to get a clean slate and remove unused or problematic files (e.g., student ZIPs, Sphinx-related files) to reduce clutter.
  • If a file was saved elsewhere, verify and clean that location too, but understand that recent lists may still reflect previous actions (e.g., recent items list).
  • The goal is to have a clean working directory for the Sphinx setup while preserving other work elsewhere on the system.

Sphinx and OS Context

  • The steps apply across environments:
    • Windows with WSL (Windows Subsystem for Linux)
    • macOS (Mac instructions are included in the workflow; they will be kept if correct, otherwise fixed).
  • The instructor emphasizes that some steps are “advanced” but building familiarity early will pay off later when dealing with larger projects (e.g., COVID-related story example).

Downloading, Extracting, and Organizing the Archive

  • Locate the Sphinx ZIP (SS Zip) in the Downloads folder.
  • Right-click the ZIP and choose Extract All; accept the extraction destination (often the Downloads folder, though moving to another folder is also common).
  • If prompted to extract, you may see options like "Do it for all current items"; choose appropriately.
  • If you cancel a transfer or extraction, you may need to re-run the extraction or re-download; the goal is to have the extracted folder (e.g., SS/Sszip contents) available for further steps.
  • After extraction, verify that the contents include a folder named something like SS (which contains a subfolder such as source) and that inside source there are files to work with.
  • If multiple versions of the ZIP exist on the server, rename or delete older copies to avoid confusion and ensure you are using the correct one.

File System Navigation and Structure (WSL/Windows/Linux cross-setup)

  • You may move from Windows into a Linux context (WSL) where you can access Windows drives (e.g., the C drive) from within Linux.
  • Typical structure examples mentioned:
    • A root-like structure where the C drive appears under the Linux file system (e.g., /mnt/c or a mapped root)
    • A project directory tree that includes folders like general, sphinx, and source
    • SS ZIP contents placed under a specific project location (e.g., SS, then a source folder inside SS)
  • The instructor references navigating to specific folders (e.g., an initial C drive path, then into a sphinx folder, then into source).
  • The goal is to locate the Sphinx project files, ensure the correct version is used, and prepare the environment for the build.

Commands, Pasting, and Terminal Etiquette

  • When copying commands from a document or another screen, the fastest approach is to triple-click a line to select it, then copy (Ctrl+C) and paste into the terminal (Ctrl+V or terminal-specific paste, which may be Ctrl+Shift+V).
  • Common basic commands mentioned or implied:
    • ls -laF to list files with details and type indicators
    • cd <path> to change directories
    • pwd to print the current directory
    • cp <src> <dest> to copy files
    • rm -r <path> or rm -rf <path> to remove files/directories (dangerous; use with caution)
    • mkdir <dir> to create directories
    • cat <file> to display file contents
    • sudo <command> to run commands with elevated privileges when needed (password prompt)
  • A safety note: rm -r and rm -rf can erase large parts of the filesystem if used incorrectly; always confirm the target directory before executing.

Building and Installing in a Safe, Incremental Way

  • The instructor walks through a sequence of steps that resemble building or configuring a project in a Linux-like environment (WSL) from within Windows:
    • Ensure prerequisites are in place (a clean workspace, correct unzip/extract state, and the right OS context).
    • Move into the project directory (e.g., navigate to the extracted SS/Sphinx content and into the source folder).
    • Use a build or setup script path (e.g., a path that looks like sphinx.build/buildminusbhtml or similar) and follow the prompts.
    • If an instruction references a particular script or directory depth, follow the path step by step (e.g., cd into the sphinx folder, then into source).
  • When encountering permission issues, prefix commands with sudo and enter your password once; this often resolves access-denied errors during installation steps.
  • If a step appears to fail (e.g., a command not found), back up to the previous safe step, verify prerequisites (like installing necessary packages or setting up a Python virtual environment), and re-run the relevant step.

Root vs Non-Root Safety and Best Practices

  • The instructor explicitly warns about the dangers of running commands as root in the wrong directory (e.g., wiping out the whole system) and demonstrates safer sequencing to avoid catastrophic data loss.
  • Practical rules:
    • Do not run root-level commands in unfamiliar directories.
    • Use root privileges only when necessary and only in trusted paths.
    • Keep backups or copies of critical work (zip up a copy or keep a versioned repository) to recover quickly if something goes wrong.
  • A hypothetical discussion mentions resolving a potential data wipe scenario by having a backup repository; this underscores the importance of version-controlled or stored copies of work.

Practical Steps and Verification: A Step-by-Step Recap

  • Confirm presence of all participants; share screens if needed; ensure downloads/zip are accessible.
  • Open Sphinx-related content and extract the archive to the chosen location; verify that the contents include a source directory and other expected components.
  • Switch between Windows and Linux contexts as needed (Windows Desktop, Alt+Tab for windows, Windows Task View for multiple desktops).
  • In the terminal, reach the project folder (e.g., navigate to sphinx/src), inspect contents with ls -la, and confirm a build path exists (e.g., a directory such as sphinx.build/… or similar).
  • Copy and paste a series of commands one line at a time into the terminal, watching for prompts and permission requests; use sudo when necessary and provide the password when prompted.
  • If you encounter a mismatch or a duplicate file (e.g., multiple versions on the server), rename or remove the older version to prevent confusion.
  • After completing the build/install steps, validate that the environment is operational by listing the current directory, viewing a test file with cat, and confirming that the expected build artifacts are present.

Common Issues, Troubleshooting, and Tips

  • Issue: “permission denied” when writing to a directory; solution: prepend with sudo and re-run, or adjust ownership/permissions if appropriate.
  • Issue: Multiple versions of a download on the server; solution: delete or rename older copies and stick to one confirmed version.
  • Issue: A command not found; solution: ensure prerequisites (tools, environments) are installed; re-check the required script sequence; sometimes a prior step (like virtual environment setup) was skipped.
  • Issue: Build path or environment not yet created; solution: confirm you have created and activated the necessary virtual environment before running build steps.
  • Important reminder: the sequence and the exact path names may vary across environments; adapt to the actual directory structure you see in your session.

Final Thoughts: Real-World Relevance and Implications

  • This session demonstrates foundational skills for preparing a reproducible development environment: clean workspace, correct file organization, safe use of elevated privileges, and careful stepwise execution.
  • It highlights the importance of backups and version control as safeguards against data loss when experimenting with powerful commands or system-level changes.
  • The discussion touches on practical aspects of cross-platform development (Windows/WSL and Mac), illustrating how instructors must adapt workflows to different operating systems.
  • Philosophically, it reinforces the idea that complex software projects are built incrementally: small, correct steps reduce risk and improve reliability over “magic” one-shot setups.

Homework and Closing Notes

  • The instructor mentions optics problems as a separate topic for quick help; the homework assigned relates to a convex-concave optics topic and reading a chapter (about ten minutes).
  • The overarching message: use the time to solidify understanding of file management, permissions, and basic Linux-like workflows, which will pay off when tackling more advanced topics.