chore(librarian): create docs/README.rst file during generation (#14751)

This PR creates a `docs/index.rst` file for a new library that is
configured and generated using librarian.

Author: ohmayr

.generator/cli.py

@@ -381,7 +381,6 @@ def _clean_up_files_after_post_processing(output: str, library_id: str):
     # Safely remove specific files if they exist using pathlib.
     Path(f"{output}/{path_to_library}/CHANGELOG.md").unlink(missing_ok=True)
     Path(f"{output}/{path_to_library}/docs/CHANGELOG.md").unlink(missing_ok=True)
-    Path(f"{output}/{path_to_library}/docs/README.rst").unlink(missing_ok=True)
 
     # The glob loops are already safe, as they do nothing if no files match.
     for post_processing_file in glob.glob(
@@ -501,6 +500,47 @@ def _generate_repo_metadata_file(
     _write_json_file(output_repo_metadata, metadata_content)
 
 
+def _copy_readme_to_docs(output: str, library_id: str):
+    """Copies the README.rst file for a generated library to docs/README.rst.
+
+    This function is robust against various symlink configurations that could
+    cause `shutil.copy` to fail with a `SameFileError`. It reads the content
+    from the source and writes it to the destination, ensuring the final
+    destination is a real file.
+
+    Args:
+        output(str): Path to the directory in the container where code
+            should be generated.
+        library_id(str): The library id.
+    """
+    path_to_library = f"packages/{library_id}"
+    source_path = f"{output}/{path_to_library}/README.rst"
+    docs_path = f"{output}/{path_to_library}/docs"
+    destination_path = f"{docs_path}/README.rst"
+
+    # If the source file doesn't exist (not even as a broken symlink),
+    # there's nothing to copy.
+    if not os.path.lexists(source_path):
+        return
+
+    # Read the content from the source, which will resolve any symlinks.
+    with open(source_path, "r") as f:
+        content = f.read()
+
+    # Remove any symlinks at the destination to prevent errors.
+    if os.path.islink(destination_path):
+        os.remove(destination_path)
+    elif os.path.islink(docs_path):
+        os.remove(docs_path)
+
+    # Ensure the destination directory exists as a real directory.
+    os.makedirs(docs_path, exist_ok=True)
+
+    # Write the content to the destination, creating a new physical file.
+    with open(destination_path, "w") as f:
+        f.write(content)
+
+
 def handle_generate(
     librarian: str = LIBRARIAN_DIR,
     source: str = SOURCE_DIR,
@@ -542,6 +582,7 @@ def handle_generate(
         _copy_files_needed_for_post_processing(output, input, library_id)
         _generate_repo_metadata_file(output, library_id, source, apis_to_generate)
         _run_post_processor(output, library_id)
+        _copy_readme_to_docs(output, library_id)
         _clean_up_files_after_post_processing(output, library_id)
     except Exception as e:
         raise ValueError("Generation failed.") from e

.generator/test_cli.py

@@ -70,6 +70,7 @@
     _verify_library_namespace,
     _write_json_file,
     _write_text_file,
+    _copy_readme_to_docs,
     handle_build,
     handle_configure,
     handle_generate,
@@ -1514,3 +1515,100 @@ def test_stage_gapic_library(mocker):
     mock_shutil_copytree.assert_called_once_with(
         tmp_dir, staging_dir, dirs_exist_ok=True
     )
+
+
+def test_copy_readme_to_docs(mocker):
+    """Tests that the README.rst is copied to the docs directory, handling symlinks."""
+    mock_makedirs = mocker.patch("os.makedirs")
+    mock_shutil_copy = mocker.patch("shutil.copy")
+    mock_os_islink = mocker.patch("os.path.islink", return_value=False)
+    mock_os_remove = mocker.patch("os.remove")
+    mock_os_lexists = mocker.patch("os.path.lexists", return_value=True)
+    mock_open = mocker.patch("builtins.open", mocker.mock_open(read_data="dummy content"))
+
+    output = "output"
+    library_id = "google-cloud-language"
+    _copy_readme_to_docs(output, library_id)
+
+    expected_source = "output/packages/google-cloud-language/README.rst"
+    expected_docs_path = "output/packages/google-cloud-language/docs"
+    expected_destination = "output/packages/google-cloud-language/docs/README.rst"
+
+    mock_os_lexists.assert_called_once_with(expected_source)
+    mock_open.assert_any_call(expected_source, "r")
+    mock_os_islink.assert_any_call(expected_destination)
+    mock_os_islink.assert_any_call(expected_docs_path)
+    mock_os_remove.assert_not_called()
+    mock_makedirs.assert_called_once_with(expected_docs_path, exist_ok=True)
+    mock_open.assert_any_call(expected_destination, "w")
+    mock_open().write.assert_called_once_with("dummy content")
+
+
+def test_copy_readme_to_docs_handles_symlink(mocker):
+    """Tests that the README.rst is copied to the docs directory, handling symlinks."""
+    mock_makedirs = mocker.patch("os.makedirs")
+    mock_shutil_copy = mocker.patch("shutil.copy")
+    mock_os_islink = mocker.patch("os.path.islink")
+    mock_os_remove = mocker.patch("os.remove")
+    mock_os_lexists = mocker.patch("os.path.lexists", return_value=True)
+    mock_open = mocker.patch("builtins.open", mocker.mock_open(read_data="dummy content"))
+
+    # Simulate docs_path being a symlink
+    mock_os_islink.side_effect = [False, True] # First call for destination_path, second for docs_path
+
+    output = "output"
+    library_id = "google-cloud-language"
+    _copy_readme_to_docs(output, library_id)
+
+    expected_source = "output/packages/google-cloud-language/README.rst"
+    expected_docs_path = "output/packages/google-cloud-language/docs"
+    expected_destination = "output/packages/google-cloud-language/docs/README.rst"
+
+    mock_os_lexists.assert_called_once_with(expected_source)
+    mock_open.assert_any_call(expected_source, "r")
+    mock_os_islink.assert_any_call(expected_destination)
+    mock_os_islink.assert_any_call(expected_docs_path)
+    mock_os_remove.assert_called_once_with(expected_docs_path)
+    mock_makedirs.assert_called_once_with(expected_docs_path, exist_ok=True)
+    mock_open.assert_any_call(expected_destination, "w")
+    mock_open().write.assert_called_once_with("dummy content")
+
+
+def test_copy_readme_to_docs_destination_path_is_symlink(mocker):
+    """Tests that the README.rst is copied to the docs directory, handling destination_path being a symlink."""
+    mock_makedirs = mocker.patch("os.makedirs")
+    mock_shutil_copy = mocker.patch("shutil.copy")
+    mock_os_islink = mocker.patch("os.path.islink", return_value=True)
+    mock_os_remove = mocker.patch("os.remove")
+    mock_os_lexists = mocker.patch("os.path.lexists", return_value=True)
+    mock_open = mocker.patch("builtins.open", mocker.mock_open(read_data="dummy content"))
+
+    output = "output"
+    library_id = "google-cloud-language"
+    _copy_readme_to_docs(output, library_id)
+
+    expected_destination = "output/packages/google-cloud-language/docs/README.rst"
+    mock_os_remove.assert_called_once_with(expected_destination)
+
+
+def test_copy_readme_to_docs_source_not_exists(mocker):
+    """Tests that the function returns early if the source README.rst does not exist."""
+    mock_makedirs = mocker.patch("os.makedirs")
+    mock_shutil_copy = mocker.patch("shutil.copy")
+    mock_os_islink = mocker.patch("os.path.islink")
+    mock_os_remove = mocker.patch("os.remove")
+    mock_os_lexists = mocker.patch("os.path.lexists", return_value=False)
+    mock_open = mocker.patch("builtins.open", mocker.mock_open(read_data="dummy content"))
+
+    output = "output"
+    library_id = "google-cloud-language"
+    _copy_readme_to_docs(output, library_id)
+
+    expected_source = "output/packages/google-cloud-language/README.rst"
+
+    mock_os_lexists.assert_called_once_with(expected_source)
+    mock_open.assert_not_called()
+    mock_os_islink.assert_not_called()
+    mock_os_remove.assert_not_called()
+    mock_makedirs.assert_not_called()
+    mock_shutil_copy.assert_not_called()