chore: split sphinxdocs into its own module (#3629)

Splitting sphinxdocs into its own module is desirable to reduce the
dependency
footprint of rules_python outside of development mode modules.

Work towards #2511

---------

Co-authored-by: Ignas Anikevicius <240938+aignas@users.noreply.github.com>

Author: rickeylev

.bazelci/presubmit.yml

@@ -174,6 +174,23 @@ tasks:
     test_targets: ["//..."]
     working_directory: gazelle
 
+  sphinxdocs_ubuntu:
+    name: "Sphinxdocs: Ubuntu"
+    working_directory: "sphinxdocs"
+    platform: ubuntu2204
+    build_targets:
+      - "//..."
+    test_targets:
+      - "//..."
+  sphinxdocs_mac:
+    name: "Sphinxdocs: Mac"
+    working_directory: "sphinxdocs"
+    platform: macos_arm64
+    build_targets:
+      - "//..."
+    test_targets:
+      - "//..."
+
   ubuntu_min_workspace:
     <<: *minimum_supported_version
     <<: *reusable_config

.bazelignore

@@ -29,6 +29,7 @@ gazelle/examples/bzlmod_build_file_generation/bazel-bin
 gazelle/examples/bzlmod_build_file_generation/bazel-bzlmod_build_file_generation
 gazelle/examples/bzlmod_build_file_generation/bazel-out
 gazelle/examples/bzlmod_build_file_generation/bazel-testlog
+sphinxdocs
 tests/integration/compile_pip_requirements/bazel-compile_pip_requirements
 tests/integration/local_toolchains/bazel-local_toolchains
 tests/integration/py_cc_toolchain_registered/bazel-py_cc_toolchain_registered

.bcr/config.yml

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-moduleRoots: [".", "gazelle"]
+moduleRoots: [".", "gazelle", "sphinxdocs"]

.bcr/sphinxdocs/metadata.template.json

@@ -0,0 +1,21 @@
+{
+    "homepage": "https://github.com/bazel-contrib/rules_python",
+    "maintainers": [
+        {
+            "name": "Richard Levasseur",
+            "email": "richardlev@gmail.com",
+            "github": "rickeylev"
+        },
+        {
+            "name": "Ignas Anikevicius",
+            "email": "bcr-ignas@use.startmail.com",
+            "github": "aignas"
+        }
+    ],
+    "repository": [
+        "github:bazelbuild/rules_python",
+        "github:bazel-contrib/rules_python"
+    ],
+    "versions": [],
+    "yanked_versions": {}
+}

.bcr/sphinxdocs/presubmit.yml

@@ -0,0 +1,23 @@
+bcr_test_module:
+  module_path: "integration_tests/bcr"
+  matrix:
+    platform: ["debian11", "macos", "ubuntu2204"]
+    bazel: [8.*, 9.*]
+  tasks:
+    run_tests:
+      name: "Run test module"
+      platform: ${{ platform }}
+      bazel: ${{ bazel }}
+      shell_commands:
+        - "echo 'common --override_module=rules_python=' >> .bazelrc"
+      batch_commands:
+        - "echo common --override_module=rules_python= >> .bazelrc"
+      test_flags:
+        # Minimum bazel supported C++
+        - "--keep_going"
+        - '--cxxopt=-std=c++17'
+        - '--host_cxxopt=-std=c++17'
+      build_targets:
+        - "//..."
+      test_targets:
+        - "//..."

.bcr/sphinxdocs/source.template.json

@@ -0,0 +1,5 @@
+{
+    "integrity": "",
+    "strip_prefix": "{REPO}-{VERSION}/sphinxdocs",
+    "url": "https://github.com/{OWNER}/{REPO}/releases/download/{TAG}/rules_python-{TAG}.tar.gz"
+}

MODULE.bazel

@@ -211,10 +211,13 @@ pip.parse(
 )
 use_repo(pip, "rules_python_publish_deps")
 
-# Not a dev dependency to allow usage of //sphinxdocs code, which refers to stardoc repos.
-bazel_dep(name = "stardoc", version = "0.7.2", repo_name = "io_bazel_stardoc")
-
 # ===== DEV ONLY DEPS AND SETUP BELOW HERE =====
+bazel_dep(name = "sphinxdocs", version = "0.0.0", dev_dependency = True)
+local_path_override(
+    module_name = "sphinxdocs",
+    path = "sphinxdocs",
+)
+
 bazel_dep(name = "rules_bazel_integration_test", version = "0.27.0", dev_dependency = True)
 bazel_dep(name = "rules_testing", version = "0.6.0", dev_dependency = True)
 bazel_dep(name = "rules_shell", version = "0.3.0", dev_dependency = True)

docs/BUILD.bazel

@@ -14,13 +14,13 @@
 
 load("@bazel_skylib//rules:build_test.bzl", "build_test")
 load("@dev_pip//:requirements.bzl", "requirement")
+load("@sphinxdocs//sphinxdocs:readthedocs.bzl", "readthedocs_install")
+load("@sphinxdocs//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
+load("@sphinxdocs//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
+load("@sphinxdocs//sphinxdocs:sphinx_stardoc.bzl", "sphinx_stardoc", "sphinx_stardocs")
 load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED")  # buildifier: disable=bzl-visibility
 load("//python/private:common_labels.bzl", "labels")  # buildifier: disable=bzl-visibility
 load("//python/uv:lock.bzl", "lock")  # buildifier: disable=bzl-visibility
-load("//sphinxdocs:readthedocs.bzl", "readthedocs_install")
-load("//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
-load("//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
-load("//sphinxdocs:sphinx_stardoc.bzl", "sphinx_stardoc", "sphinx_stardocs")
 
 package(default_visibility = ["//:__subpackages__"])
 
@@ -63,7 +63,7 @@ sphinx_docs(
     renamed_srcs = {
         "//:CHANGELOG.md": "changelog.md",
         "//:CONTRIBUTING.md": "contributing.md",
-        "//sphinxdocs/inventories:bazel_inventory": "bazel_inventory.inv",
+        "@sphinxdocs//sphinxdocs/inventories:bazel_inventory": "bazel_inventory.inv",
     },
     sphinx = ":sphinx-build",
     strip_prefix = package_name() + "/",
@@ -73,7 +73,7 @@ sphinx_docs(
         ":bzl_api_docs",
         ":py_api_srcs",
         ":py_runtime_pair",
-        "//sphinxdocs/docs:docs_lib",
+        "@sphinxdocs//sphinxdocs/docs:docs_lib",
     ],
 )
 
@@ -182,7 +182,7 @@ sphinx_build_binary(
         requirement("typing_extensions"),
         requirement("sphinx_autodoc2"),
         requirement("sphinx_reredirects"),
-        "//sphinxdocs/src/sphinx_bzl",
+        "@sphinxdocs//sphinxdocs/src/sphinx_bzl",
     ],
 )
 

docs/conf.py

@@ -7,7 +7,7 @@
 copyright = "2023, The Bazel Authors"
 author = "Bazel"
 
-# NOTE: These are overriden by -D flags via --//sphinxdocs:extra_defines
+# NOTE: These are overriden by -D flags via --@sphinxdocs//sphinxdocs:extra_defines
 version = "0.0.0"
 release = version
 
@@ -139,7 +139,10 @@
 
 # --- Extlinks configuration
 extlinks = {
-    "gh-issue": (f"https://github.com/bazel-contrib/rules_python/issues/%s", "#%s issue"),
+    "gh-issue": (
+        f"https://github.com/bazel-contrib/rules_python/issues/%s",
+        "#%s issue",
+    ),
     "gh-path": (f"https://github.com/bazel-contrib/rules_python/tree/main/%s", "%s"),
     "gh-pr": (f"https://github.com/bazel-contrib/rules_python/pull/%s", "#%s PR"),
 }

docs/readthedocs_build.sh

@@ -5,19 +5,19 @@ set -eou pipefail
 declare -a extra_env
 while IFS='=' read -r -d '' name value; do
   if [[ "$name" == READTHEDOCS* ]]; then
-    extra_env+=("--//sphinxdocs:extra_env=$name=$value")
+    extra_env+=("--@sphinxdocs//sphinxdocs:extra_env=$name=$value")
   fi
 done < <(env -0)
 
 # In order to get the build number, we extract it from the host name
-extra_env+=("--//sphinxdocs:extra_env=HOSTNAME=$HOSTNAME")
+extra_env+=("--@sphinxdocs//sphinxdocs:extra_env=HOSTNAME=$HOSTNAME")
 
 export RULES_PYTHON_ENABLE_PIPSTAR=1
 
 set -x
 export RULES_PYTHON_ENABLE_PIPSTAR=1
 bazel run \
   --config=rtd \
-  "--//sphinxdocs:extra_defines=version=$READTHEDOCS_VERSION" \
+  "--@sphinxdocs//sphinxdocs:extra_defines=version=$READTHEDOCS_VERSION" \
   "${extra_env[@]}" \
   //docs:readthedocs_install