refactor: move docs/sphinx -> docs (#2130)

The sphinx sub-dir was only temporary as the sphinx-based docgen was
implemented. With that done, the files can be moved up into the regular
docs directory.

Author: rickeylev

.github/dependabot.yml

@@ -10,7 +10,7 @@ updates:
   - package-ecosystem: "pip"
     directories:
       # Maintain dependencies for our tools
-      - "/docs/sphinx"
+      - "/docs"
       - "/tools/publish"
     schedule:
       interval: "weekly"

.readthedocs.yml

@@ -11,4 +11,4 @@ build:
     - bazel version
     # Put the actual build behind a shell script because its easier to modify than
     # the yaml config.
-    - docs/sphinx/readthedocs_build.sh
+    - docs/readthedocs_build.sh

CONTRIBUTING.md

@@ -148,7 +148,7 @@ merged:
 
 * **requirements lock files**: These are usually generated by a
   `compile_pip_requirements` update target, which is usually in the same directory.
-  e.g. `bazel run //docs/sphinx:requirements.update`
+  e.g. `bazel run //docs:requirements.update`
 
 ## Core rules
 

MODULE.bazel

@@ -93,7 +93,7 @@ dev_pip = use_extension(
 dev_pip.parse(
     hub_name = "dev_pip",
     python_version = "3.11",
-    requirements_lock = "//docs/sphinx:requirements.txt",
+    requirements_lock = "//docs:requirements.txt",
 )
 dev_pip.parse(
     hub_name = "pypiserver",

WORKSPACE

@@ -122,7 +122,7 @@ install_pypiserver()
 pip_parse(
     name = "dev_pip",
     python_interpreter_target = interpreter,
-    requirements_lock = "//docs/sphinx:requirements.txt",
+    requirements_lock = "//docs:requirements.txt",
 )
 
 load("@dev_pip//:requirements.bzl", docs_install_deps = "install_deps")

docs/BUILD.bazel

@@ -1,10 +1,10 @@
-# Copyright 2017 The Bazel Authors. All rights reserved.
+# Copyright 2023 The Bazel Authors. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
-#    http://www.apache.org/licenses/LICENSE-2.0
+#     http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
@@ -13,10 +13,199 @@
 # limitations under the License.
 
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
+load("@dev_pip//:requirements.bzl", "requirement")
+load("//python:py_binary.bzl", "py_binary")
+load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED")  # buildifier: disable=bzl-visibility
+load("//python/private:util.bzl", "IS_BAZEL_7_OR_HIGHER")  # buildifier: disable=bzl-visibility
+load("//sphinxdocs:readthedocs.bzl", "readthedocs_install")
+load("//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
+load("//sphinxdocs:sphinx_stardoc.bzl", "sphinx_stardoc", "sphinx_stardocs")
 
-# NOTE: Only public visibility for historical reasons.
-# This package is only for rules_python to generate its own docs.
-package(default_visibility = ["//visibility:public"])
+package(default_visibility = ["//:__subpackages__"])
+
+# We only build for Linux and Mac because:
+# 1. The actual doc process only runs on Linux
+# 2. Mac is a common development platform, and is close enough to Linux
+#    it's feasible to make work.
+# Making CI happy under Windows is too much of a headache, though, so we don't
+# bother with that.
+_TARGET_COMPATIBLE_WITH = select({
+    "@platforms//os:linux": [],
+    "@platforms//os:macos": [],
+    "//conditions:default": ["@platforms//:incompatible"],
+}) if IS_BAZEL_7_OR_HIGHER else ["@platforms//:incompatible"]
+
+# See README.md for instructions. Short version:
+# * `bazel run //docs:docs.serve` in a separate terminal
+# * `ibazel build //docs:docs` to automatically rebuild docs
+sphinx_docs(
+    name = "docs",
+    srcs = glob(
+        include = [
+            "*.md",
+            "**/*.md",
+            "_static/**",
+            "_includes/**",
+        ],
+        exclude = [
+            "README.md",
+            "_*",
+            "*.inv*",
+        ],
+    ),
+    config = "conf.py",
+    formats = [
+        "html",
+    ],
+    renamed_srcs = {
+        "//:CHANGELOG.md": "changelog.md",
+        "//:CONTRIBUTING.md": "contributing.md",
+        "//sphinxdocs/inventories:bazel_inventory": "bazel_inventory.inv",
+    },
+    sphinx = ":sphinx-build",
+    strip_prefix = package_name() + "/",
+    tags = ["docs"],
+    target_compatible_with = _TARGET_COMPATIBLE_WITH,
+    deps = [
+        ":bzl_api_docs",
+        "//sphinxdocs/docs:docs_lib",
+    ],
+)
+
+sphinx_stardocs(
+    name = "bzl_api_docs",
+    srcs = [
+        "//python:defs_bzl",
+        "//python:packaging_bzl",
+        "//python:pip_bzl",
+        "//python:py_binary_bzl",
+        "//python:py_cc_link_params_info_bzl",
+        "//python:py_library_bzl",
+        "//python:py_runtime_bzl",
+        "//python:py_runtime_info_bzl",
+        "//python:py_test_bzl",
+        "//python/cc:py_cc_toolchain_info_bzl",
+        "//python/entry_points:py_console_script_binary_bzl",
+        "//python/private/common:py_binary_rule_bazel_bzl",
+        "//python/private/common:py_library_rule_bazel_bzl",
+        "//python/private/common:py_runtime_rule_bzl",
+        "//python/private/common:py_test_rule_bazel_bzl",
+    ] + ([
+        # Bazel 6 + Stardoc isn't able to parse something about the python bzlmod extension
+        "//python/extensions:python_bzl",
+    ] if IS_BAZEL_7_OR_HIGHER else []) + ([
+        # This depends on @pythons_hub, which is only created under bzlmod,
+        "//python/extensions:pip_bzl",
+    ] if IS_BAZEL_7_OR_HIGHER and BZLMOD_ENABLED else []),
+    prefix = "api/",
+    tags = ["docs"],
+    target_compatible_with = _TARGET_COMPATIBLE_WITH,
+)
+
+sphinx_stardoc(
+    name = "py_cc_toolchain",
+    src = "//python/private:py_cc_toolchain_rule.bzl",
+    prefix = "api/",
+    public_load_path = "//python/cc:py_cc_toolchain.bzl",
+    tags = ["docs"],
+    target_compatible_with = _TARGET_COMPATIBLE_WITH,
+    deps = ["//python/cc:py_cc_toolchain_bzl"],
+)
+
+sphinx_stardoc(
+    name = "py_runtime_pair",
+    src = "//python/private:py_runtime_pair_rule_bzl",
+    public_load_path = "//python:py_runtime_pair.bzl",
+    tags = ["docs"],
+    target_compatible_with = _TARGET_COMPATIBLE_WITH,
+)
+
+readthedocs_install(
+    name = "readthedocs_install",
+    docs = [":docs"],
+    target_compatible_with = _TARGET_COMPATIBLE_WITH,
+)
+
+sphinx_build_binary(
+    name = "sphinx-build",
+    target_compatible_with = _TARGET_COMPATIBLE_WITH,
+    deps = [
+        requirement("sphinx"),
+        requirement("sphinx_rtd_theme"),
+        requirement("myst_parser"),
+        requirement("readthedocs_sphinx_ext"),
+        requirement("typing_extensions"),
+        "//sphinxdocs/src/sphinx_bzl",
+    ],
+)
+
+_REQUIREMENTS_TARGET_COMPATIBLE_WITH = select({
+    "@platforms//os:linux": [],
+    "@platforms//os:macos": [],
+    "@platforms//os:windows": [],
+    "//conditions:default": ["@platforms//:incompatible"],
+}) if BZLMOD_ENABLED else ["@platforms//:incompatible"]
+
+# Run bazel run //docs:requirements.update
+genrule(
+    name = "requirements",
+    srcs = ["pyproject.toml"],
+    outs = ["_requirements.txt"],
+    cmd = "$(UV_BIN) pip compile " + " ".join([
+        "--custom-compile-command='bazel run //docs:requirements.update'",
+        "--generate-hashes",
+        "--universal",
+        "--emit-index-url",
+        "--no-strip-extras",
+        "--no-build",
+        "--python=$(PYTHON3)",
+        "$<",
+        "--output-file=$@",
+        # Always try upgrading
+        "--upgrade",
+    ]),
+    tags = [
+        "local",
+        "manual",
+        "no-cache",
+    ],
+    target_compatible_with = _REQUIREMENTS_TARGET_COMPATIBLE_WITH,
+    toolchains = [
+        "//python/uv:current_toolchain",
+        "//python:current_py_toolchain",
+    ],
+)
+
+# Write a script that can be used for updating the in-tree version of the
+# requirements file
+write_file(
+    name = "gen_update_requirements",
+    out = "requirements.update.py",
+    content = [
+        "from os import environ",
+        "from pathlib import Path",
+        "from sys import stderr",
+        "",
+        'src = Path(environ["REQUIREMENTS_FILE"])',
+        'dst = Path(environ["BUILD_WORKSPACE_DIRECTORY"]) / "docs" / "requirements.txt"',
+        'print(f"Writing requirements contents from {src} to {dst}", file=stderr)',
+        "dst.write_text(src.read_text())",
+        'print("Success!", file=stderr)',
+    ],
+    target_compatible_with = _REQUIREMENTS_TARGET_COMPATIBLE_WITH,
+)
+
+py_binary(
+    name = "requirements.update",
+    srcs = ["requirements.update.py"],
+    data = [":requirements"],
+    env = {
+        "REQUIREMENTS_FILE": "$(location :requirements)",
+    },
+    tags = ["manual"],
+    target_compatible_with = _REQUIREMENTS_TARGET_COMPATIBLE_WITH,
+)
 
 licenses(["notice"])  # Apache 2.0
 
@@ -26,18 +215,21 @@ alias(
     name = "defs",
     actual = "//python:defs_bzl",
     deprecation = "Use //python:defs_bzl instead; targets under //docs are internal.",
+    visibility = ["//visibility:public"],
 )
 
 alias(
     name = "bazel_repo_tools",
     actual = "//python/private:bazel_tools_bzl",
     deprecation = "Use @bazel_tools//tools:bzl_srcs instead; targets under //docs are internal.",
+    visibility = ["//visibility:public"],
 )
 
 bzl_library(
     name = "pip_install_bzl",
     deprecation = "Use //python:pip_bzl or //python/pip_install:pip_repository_bzl instead; " +
                   "targets under //docs are internal.",
+    visibility = ["//visibility:public"],
     deps = [
         "//python:pip_bzl",
         "//python/pip_install:pip_repository_bzl",
@@ -49,4 +241,5 @@ alias(
     actual = "//python/pip_install:pip_repository_bzl",
     deprecation = "Use //python/pip_install:pip_repository_bzl instead; Both the requirements " +
                   "parser and targets under //docs are internal",
+    visibility = ["//visibility:public"],
 )

docs/sphinx/README.md docs/README.md

@@ -18,8 +18,8 @@ server to serve the generated HTML, and re-generating the HTML when sources
 change. The quick start is:
 
 ```
-bazel run //docs/sphinx:docs.serve  # Run in separate terminal
-ibazel build //docs/sphinx:docs  # Automatically rebuilds docs
+bazel run //docs:docs.serve  # Run in separate terminal
+ibazel build //docs:docs  # Automatically rebuilds docs
 ```
 
 This will build the docs and start a local webserver at http://localhost:8000
@@ -47,14 +47,14 @@ integrates with Sphinx functionality such as automatic cross references,
 creating indexes, and using concise markup to generate rich documentation.
 
 MyST features and behaviors are controlled by the Sphinx configuration file,
-`docs/sphinx/conf.py`. For more info, see https://myst-parser.readthedocs.io.
+`docs/conf.py`. For more info, see https://myst-parser.readthedocs.io.
 
 ## Sphinx configuration
 
 The Sphinx-specific configuration files and input doc files live in
-docs/sphinx.
+docs/.
 
-The Sphinx configuration is `docs/sphinx/conf.py`. See
+The Sphinx configuration is `docs/conf.py`. See
 https://www.sphinx-doc.org/ for details about the configuration file.
 
 ## Readthedocs configuration

docs/sphinx/_includes/py_console_script_binary.md docs/_includes/py_console_script_binary.md

@@ -16,7 +16,7 @@
 # for more settings
 
 # Any extensions here not built into Sphinx must also be added to
-# the dependencies of //docs/sphinx:sphinx-builder
+# the dependencies of //docs:sphinx-builder
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
@@ -114,7 +114,7 @@
     "READTHEDOCS": False,
     "PRODUCTION_DOMAIN": "readthedocs.org",
     # This is the path to a page's source (after the github user/repo/commit)
-    "conf_py_path": "/docs/sphinx/",
+    "conf_py_path": "/docs/",
     "github_user": "bazelbuild",
     "github_repo": "rules_python",
     # The git version that was checked out, e.g. the tag or branch name

docs/sphinx/_static/css/custom.css docs/_static/css/custom.css

@@ -324,7 +324,7 @@ the {gh-path}`examples/bzlmod/MODULE.bazel` example.
 When using this feature during the `pip` extension evaluation you will see the accessed indexes similar to below:
 ```console
 Loading: 0 packages loaded
-    currently loading: docs/sphinx
+    currently loading: docs/
     Fetching module extension pip in @@//python/extensions:pip.bzl; starting
     Fetching https://pypi.org/simple/twine/
 ```

docs/sphinx/api/index.md docs/api/index.md

@@ -17,4 +17,4 @@ bazel run \
   --config=rtd \
   "--//sphinxdocs:extra_defines=version=$READTHEDOCS_VERSION" \
   "${extra_env[@]}" \
-  //docs/sphinx:readthedocs_install
+  //docs:readthedocs_install