Remove man/HTML docs from tarball, require Sphinx instead

Advantages of prebuilt docs:
- convenient for users who compile the tarball
- convenient for packagers who don't have sphinx-build packaged
  (but packaging/installing that should be easy nowadays?
  see https://github.com/fish-shell/fish-shell/issues/12052#issuecomment-3520336984)

Disadvantages:
- Extra build stage / code path
- Users who switch from building from tarball to building from source
  might be surprised to lose docs.
- People put the [tarballs into Git repositories](https://salsa.debian.org/debian/fish), which seems weird.

Remove the tarball.

Let's hope this is not too annoying to users who build on outdated
distros that don't have sphinx -- but those users can probably use
our static builds, skipping all compilation.

To avoid breaking packagers who use `-DBUILD_DOCS=OFF` (which still
installs prebuilt docs), rename the option.

Closes #12088

.github/workflows/release.yml

@@ -172,7 +172,7 @@ jobs:
           echo "$MACOS_NOTARIZE_JSON" >/tmp/notarize.json
           ./build_tools/make_macos_pkg.sh -s -f /tmp/app.p12 \
             -i /tmp/installer.p12 -p "$MAC_CODESIGN_PASSWORD" \
-            -n -j /tmp/notarize.json -- -c "-DBUILD_DOCS=ON"
+            -n -j /tmp/notarize.json -- -c "-DWITH_DOCS=ON"
           version=$(git describe)
           [ -f "${FISH_ARTEFACT_PATH}/fish-$version.app.zip" ]
           [ -f "${FISH_ARTEFACT_PATH}/fish-$version.pkg" ]

CHANGELOG.rst

@@ -23,6 +23,9 @@ Improved terminal support
 
 For distributors and developers
 -------------------------------
+- Tarballs no longer contain prebuilt documentation,
+  so building and installing documentation requires Sphinx.
+  To avoid users accidentally losing docs, the ``BUILD_DOCS`` and ``INSTALL_DOCS`` configuration options have been replaced with a new ``WITH_DOCS`` option.
 - ``fish_key_reader`` and ``fish_indent`` are now hardlinks to ``fish``.
 
 Regression fixes:

CMakeLists.txt

@@ -44,7 +44,6 @@ set(VARS_FOR_CARGO
     "${FISH_PCRE2_BUILDFLAG}"
     "RUSTFLAGS=$ENV{RUSTFLAGS} ${rust_debugflags}"
     "FISH_SPHINX=${SPHINX_EXECUTABLE}"
-    "FISH_USE_PREBUILT_DOCS=${USE_PREBUILT_DOCS}"
 )
 
 # Let fish pick up when we're running out of the build directory without installing

README.rst

@@ -157,7 +157,7 @@ In addition to the normal CMake build options (like ``CMAKE_INSTALL_PREFIX``), f
 - Rust_COMPILER=path - the path to rustc. If not set, cmake will check $PATH and ~/.cargo/bin
 - Rust_CARGO=path - the path to cargo. If not set, cmake will check $PATH and ~/.cargo/bin
 - Rust_CARGO_TARGET=target - the target to pass to cargo. Set this for cross-compilation.
-- BUILD_DOCS=ON|OFF - whether to build the documentation. This is automatically set to OFF when Sphinx isn't installed.
+- WITH_DOCS=ON|OFF - whether to build the documentation. By default, this is ON when Sphinx is installed.
 - FISH_USE_SYSTEM_PCRE2=ON|OFF - whether to use an installed pcre2. This is normally autodetected.
 - MAC_CODESIGN_ID=String|OFF - the codesign ID to use on Mac, or "OFF" to disable codesigning.
 - WITH_GETTEXT=ON|OFF - whether to include translations.

build.rs

@@ -97,9 +97,6 @@ fn detect_cfgs(target: &mut Target) {
             }
         }),
         ("small_main_stack", &has_small_stack),
-        ("use_prebuilt_docs", &|_| {
-            env_var("FISH_USE_PREBUILT_DOCS").is_some_and(|v| v == "TRUE")
-        }),
         ("using_cmake", &|_| {
             option_env!("FISH_CMAKE_BINARY_DIR").is_some()
         }),

build_tools/make_tarball.sh

@@ -1,26 +1,12 @@
 #!/bin/sh
 
 # Script to generate a tarball
-# We use git to output a tree. But we also want to build the user documentation
-# and put that in the tarball, so that nobody needs to have sphinx installed
-# to build it.
 # Outputs to $FISH_ARTEFACT_PATH or ~/fish_built by default
 
 # Exit on error
 set -e
 
 # We will generate a tarball with a prefix "fish-VERSION"
-# git can do that automatically for us via git-archive
-# but to get the documentation in, we need to make a symlink called "fish-VERSION"
-# and tar from that, so that the documentation gets the right prefix
-
-# Use Ninja if available, as it automatically parallelises
-BUILD_TOOL="make"
-BUILD_GENERATOR="Unix Makefiles"
-if command -v ninja >/dev/null; then
-    BUILD_TOOL="ninja"
-    BUILD_GENERATOR="Ninja"
-fi
 
 # We need GNU tar as that supports the --mtime and --transform options
 TAR=notfound
@@ -41,12 +27,6 @@ wd="$PWD"
 
 # Get the version
 VERSION=$(build_tools/git_version_gen.sh --stdout 2>/dev/null)
-tag_creation_date=$(
-    # If not dirty (i.e. we're building an immutable tag), pin the build date.
-    if [ "$VERSION" = "$(git describe)" ]; then
-        git log --format=%ad '--date=format:%b %d, %Y' -1
-    fi
-)
 
 # The name of the prefix, which is the directory that you get when you untar
 prefix="fish-$VERSION"
@@ -65,16 +45,10 @@ git archive --format=tar --prefix="$prefix"/ HEAD > "$path"
 PREFIX_TMPDIR=$(mktemp -d)
 cd "$PREFIX_TMPDIR"
 echo "$VERSION" > version
-cmake -G "$BUILD_GENERATOR" -DCMAKE_BUILD_TYPE=Debug "$wd"
-mkdir $PWD/user_doc/src
-FISH_SPHINX_BUILD_DATE=$tag_creation_date \
-$BUILD_TOOL doc
 
-TAR_APPEND="$TAR --append --file=$path --mtime=now --owner=0 --group=0 \
+$TAR --append --file=$path --mtime=now --owner=0 --group=0 \
-    --mode=g+w,a+rX --transform s/^/$prefix\//"
+    --mode=g+w,a+rX --transform "s/^/$prefix\//" \
-$TAR_APPEND --no-recursion user_doc
+    version
-$TAR_APPEND user_doc/html user_doc/man
-$TAR_APPEND version
 
 cd -
 rm -r "$PREFIX_TMPDIR"

cmake/Docs.cmake

@@ -39,48 +39,32 @@ add_custom_target(sphinx-manpages
     DEPENDS CHECK-FISH-BUILD-VERSION-FILE
     COMMENT "Building man pages with Sphinx")
 
-if(SPHINX_EXECUTABLE)
+if(NOT DEFINED WITH_DOCS) # Don't check for legacy options if the new one is defined, to help bisecting.
-    option(BUILD_DOCS "build documentation (requires Sphinx)" ON)
+    if(DEFINED BUILD_DOCS)
-else(SPHINX_EXECUTABLE)
+        message(FATAL_ERROR "the BUILD_DOCS option is no longer supported, use -DWITH_DOCS=ON|OFF")
-    option(BUILD_DOCS "build documentation (requires Sphinx)" OFF)
+    endif()
-endif(SPHINX_EXECUTABLE)
+    if(DEFINED INSTALL_DOCS)
+        message(FATAL_ERROR "the INSTALL_DOCS option is no longer supported, use -DWITH_DOCS=ON|OFF")
+    endif()
+endif()
 
-if(BUILD_DOCS AND NOT SPHINX_EXECUTABLE)
+if(SPHINX_EXECUTABLE)
+    option(WITH_DOCS "build documentation (requires Sphinx)" ON)
+else()
+    option(WITH_DOCS "build documentation (requires Sphinx)" OFF)
+endif()
+
+if(WITH_DOCS AND NOT SPHINX_EXECUTABLE)
     message(FATAL_ERROR "build documentation selected, but sphinx-build could not be found")
 endif()
 
-if(IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/user_doc/html
+add_feature_info(Documentation WITH_DOCS "user manual and documentation")
-   AND IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/user_doc/man)
-    set(HAVE_PREBUILT_DOCS TRUE)
-else()
-    set(HAVE_PREBUILT_DOCS FALSE)
-endif()
 
-if(BUILD_DOCS OR HAVE_PREBUILT_DOCS)
+if(WITH_DOCS)
-    set(INSTALL_DOCS ON)
-else()
-    set(INSTALL_DOCS OFF)
-endif()
-
-add_feature_info(Documentation INSTALL_DOCS "user manual and documentation")
-
-set(USE_PREBUILT_DOCS FALSE)
-if(BUILD_DOCS)
     configure_file("${SPHINX_SRC_DIR}/conf.py" "${SPHINX_BUILD_DIR}/conf.py" @ONLY)
     add_custom_target(doc ALL
                       DEPENDS sphinx-docs sphinx-manpages)
-
     # Group docs targets into a DocsTargets folder
     set_property(TARGET doc sphinx-docs sphinx-manpages
                  PROPERTY FOLDER cmake/DocTargets)
-
+endif()
-elseif(HAVE_PREBUILT_DOCS)
-    set(USE_PREBUILT_DOCS TRUE)
-    if(NOT CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR)
-        # Out of tree build - link the prebuilt documentation to the build tree
-        add_custom_target(link_doc ALL)
-        add_custom_command(TARGET link_doc
-            COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/user_doc ${CMAKE_CURRENT_BINARY_DIR}/user_doc
-            POST_BUILD)
-    endif()
-endif(BUILD_DOCS)

src/builtins/status.rs

@@ -326,12 +326,7 @@ fn iter() -> rust_embed::Filenames {
 }
 
 cfg_if!(
-    if #[cfg(use_prebuilt_docs)] {
+    if #[cfg(feature = "embed-manpages")] {
-        #[derive(RustEmbed)]
-        #[folder = "user_doc/man/man1"]
-        #[prefix = "man/man1/"]
-        struct Docs;
-    } else if #[cfg(feature = "embed-manpages")] {
         #[derive(RustEmbed)]
         #[folder = "$FISH_RESOLVED_BUILD_DIR/fish-man/man1"]
         #[prefix = "man/man1/"]

src/env/config_paths.rs

@@ -136,12 +136,9 @@ fn from_exec_path(unresolved_exec_path: &'static FishPath) -> Self {
                 ),
             );
             let user_doc_join = |dir| {
-                if cfg!(use_prebuilt_docs) {
+                cfg!(using_cmake)
-                    Some(workspace_root)
+                    .then_some(Path::new(BUILD_DIR))
-                } else {
+                    .map(|path| path.join("user_doc").join(dir))
-                    cfg!(using_cmake).then_some(Path::new(BUILD_DIR))
-                }
-                .map(|path| path.join("user_doc").join(dir))
             };
             // If we're in Cargo's target directory or in CMake's build directory, use the source files.
             Self {