Fixups

* Improve documentation in firedrake-configure
* Mention needing venv in install.rst
* firedrake-zenodo now works with missing packages
* Removed support for detecting old PyOP2, TSFC, FInAT repositories
  because it made the logic in firedrake-zenodo much more complicated.

docs/source/install.rst

@@ -172,6 +172,14 @@ Installing Firedrake
 Now that the right system packages are installed and PETSc is built we can now
 install Firedrake. To do this perform the following steps:
 
+#. Create a `virtual environment <https://docs.python.org/3/tutorial/venv.html>`_::
+
+      $ python3 -m venv venv-firedrake
+      $ . venv-firedrake/bin/activate
+
+   This is optional but strongly recommended to avoid polluting your system Python
+   environment.
+
 #. Set any necessary environment variables. This can be achieved using
    ``firedrake-configure``::
 
@@ -189,9 +197,9 @@ install Firedrake. To do this perform the following steps:
 
 #. Firedrake is now installed and ready for use!
 
-.. important::
+.. warning::
    Until Firedrake has versioned releases (slated for April/May 2025),
-   :doc:```firedrake-zenodo``</zenodo>` will only work with *editable* installations of
+   :doc:`firedrake-zenodo</zenodo>` will only work with *editable* installations of
    Firedrake and its components. To install Firedrake in editable mode you
    should replace the installation command above with::
 

firedrake/scripts/firedrake-zenodo

@@ -212,7 +212,6 @@ def collect_repo_shas():
             except ImportError:
                 pass
 
-        breakpoint()
         if repo:
             try:
                 shas[component] = get_git_commit_info(component, repo)
@@ -702,7 +701,7 @@ if args.release_tag:
 
 
 def encode_info_file(filename):
-    with open(join(cwd, filename), "rb") as f:
+    with open(os.path.join(cwd, filename), "rb") as f:
         data = base64.encodebytes(f.read()).decode()
         name = os.path.basename(filename)
         return (name, data)

scripts/firedrake-configure

@@ -41,14 +41,25 @@ ARCH_COMPLEX = FiredrakeArch.COMPLEX
 
 def main():
     parser = argparse.ArgumentParser(
-        description="Print out configuration options needed to install Firedrake",
+        description="""Print out the configuration options needed to install Firedrake
+
+This script takes in arguments declaring the operating system, target
+configuration (termed 'ARCH') and install step (installing system packages,
+PETSc 'configure', or preparing the environment for 'pip install') and simply
+prints options to the screen so they can be passed to the external command.
+
+If a supported operating system (Ubuntu or macOS with homebrew) is detected
+then 'firedrake-configure' will specify additional system packages to install
+that are used inside PETSc 'configure' instead of building from source.
+
+Please see https://firedrakeproject.org/install for more information."""
     )
     package_manager_group = parser.add_mutually_exclusive_group()
     package_manager_group.add_argument(
         "--package-manager",
         choices=[pm.value for pm in PackageManager],
         required=False,
-        help="The system package manager, if not provided firedrake-configure "
+        help="The system package manager, if not provided 'firedrake-configure' "
         "will attempt to guess it.",
     )
     package_manager_group.add_argument(
@@ -61,14 +72,14 @@ def main():
         "--arch",
         choices=[arch.value for arch in FiredrakeArch],
         default=ARCH_DEFAULT,
-        help="The target 'arch' to install.",
+        help="The target configuration to install.",
     )
     cmd_group = parser.add_mutually_exclusive_group(required=True)
     cmd_group.add_argument(
         "--show-system-dependencies",
         "--sysdeps",  # alias
         action="store_true",
-        help="Print out the system packages Firedrake needs.",
+        help="Print out the system packages Firedrake needs. The user must install these.",
     )
     cmd_group.add_argument(
         "--show-petsc-configure-options",
@@ -80,8 +91,7 @@ def main():
         "--show-env",
         "--env",  # alias
         action="store_true",
-        help="Print out the environment variables that need to be exported to "
-        "install Firedrake.",
+        help="Print out the environment variables that need to be exported to install Firedrake.",
     )
 
     args = parser.parse_args()