chore(migration): Migrate code from googleapis/sphinx-docfx-yaml into packages/gcp-sphinx-docfx-yaml

[ohmayr]

See #15998.

This PR should be merged with a merge-commit, not a squash-commit, in order to preserve the git history.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request consolidates the sphinx-docfx-yaml project into a monorepo by migrating its entire codebase and associated infrastructure into a dedicated package directory. This move streamlines development and maintenance by centralizing various configurations, build processes, and documentation within a unified repository structure.

Highlights

• Code Migration: The entire googleapis/sphinx-docfx-yaml repository has been migrated into a new packages/gcp-sphinx-docfx-yaml directory within the current monorepo structure. This includes all source code, documentation, configuration files, and CI/CD workflows.
• GitHub Configuration: New GitHub-specific configuration files have been added for the migrated package, including CODEOWNERS, issue templates, pull request templates, auto-labeling, Blunderbuss assignments, header checker linting, and repository synchronization settings.
• CI/CD Workflows: Kokoro and GitHub Actions workflows have been set up for the new package, covering continuous integration, presubmit tests, prerelease dependency checks, and documentation generation, utilizing trampoline scripts and secret management.
• Documentation and Testing: The package now includes its own CHANGELOG.md, README.rst, CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE, and SECURITY.md. Comprehensive unit and golden tests have been added or migrated to ensure the functionality and output of the Sphinx DocFX YAML generator.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request migrates the gcp-sphinx-docfx-yaml package to a new monorepo structure, involving extensive updates across GitHub configurations, Kokoro build scripts, and project metadata files. Key changes include updating CODEOWNERS, issue templates, CI/CD workflows, and dependency management. The review highlights several critical issues: f-string syntax errors in docfx_yaml/extension.py, outdated repository paths in Kokoro configurations, and incorrect URLs in .repo-metadata.json, CHANGELOG.md, and bug_report.md. Additionally, there's a typo in an error message and suggestions to improve logging practices by directing error/warning messages to sys.stderr and using consistent command substitution syntax in shell scripts.

I am having trouble creating individual review comments. Click here to see my feedback.

packages/gcp-sphinx-docfx-yaml/docfx_yaml/extension.py (600-601)

The f-string for this ValueError is split across two lines, which will result in a SyntaxError. It should be combined into a single line.

                    raise ValueError(f"Content in the block should be indented.Please check the docstring: \n{summary}")

packages/gcp-sphinx-docfx-yaml/docfx_yaml/extension.py (625-626)

The f-string for this ValueError is split across two lines, which will result in a SyntaxError. It should be combined into a single line.

                    raise ValueError("Content in the block should be indented."f"Please check the docstring: \n{summary}")

packages/gcp-sphinx-docfx-yaml/.kokoro/continuous/common.cfg (17-26)

The paths for build_file and TRAMPOLINE_BUILD_FILE seem to refer to the old repository structure (sphinx-docfx-yaml). Since the code is being migrated to packages/gcp-sphinx-docfx-yaml, these paths might need to be updated to reflect the new location within the monorepo (e.g., packages/gcp-sphinx-docfx-yaml/.kokoro/trampoline.sh). This same issue appears to be present in docs/common.cfg and presubmit/common.cfg as well. Please verify that these paths are correct for the new repository structure.

packages/gcp-sphinx-docfx-yaml/.repo-metadata.json (4-9)

The URLs for product_documentation, client_documentation, issue_tracker, and the repo field appear to point to the old repository (googleapis/sphinx-docfx-yaml). Since this PR is migrating the code, these values should be updated to reflect the new location.

packages/gcp-sphinx-docfx-yaml/.github/ISSUE_TEMPLATE/bug_report.md (13)

This link points to the old repository's issues. It should be updated to point to the new issue tracker for this package. This value is likely derived from .repo-metadata.json, which also seems to contain outdated information.

packages/gcp-sphinx-docfx-yaml/.kokoro/generate-docs.sh (91)

For consistency and to avoid potential issues with nesting, it's better to use $(...) for command substitution instead of backticks.

    GITHUB_TAGS=$(git describe --tags $(git rev-list --tags --max-count=1))

packages/gcp-sphinx-docfx-yaml/CHANGELOG.md (7)

The links in the changelog, such as the one on this line, point to the old repository googleapis/sphinx-docfx-yaml. These should be updated to reflect the new repository structure.

packages/gcp-sphinx-docfx-yaml/docfx_yaml/extension.py (80-81)

It's a best practice to write error messages to sys.stderr rather than sys.stdout. This allows for better separation of standard output and error streams. You'll need to import the sys module.

    print(Bcolors.FAIL + 'can not import conf.py! ' 'you should have a conf.py in working project folder' + Bcolors.ENDC, file=sys.stderr)

packages/gcp-sphinx-docfx-yaml/docfx_yaml/extension.py (432)

There is a typo in the error message. "enoucntered" should be "encountered".

        raise ValueError(f"Wrong formatting encountered for \n{line}")

packages/gcp-sphinx-docfx-yaml/docfx_yaml/extension.py (1475)

This error message should be printed to sys.stderr instead of sys.stdout for better error handling and stream separation. You'll need to import the sys module.

            print(f"Could not format the given code: \n{e})", file=sys.stderr)

packages/gcp-sphinx-docfx-yaml/docfx_yaml/writer.py (1157)

System message warnings should be printed to sys.stderr to separate them from standard output. You'll need to import the sys module.

        print(bcolors.WARNING + "System message warnings: %s" % node.astext() + bcolors.ENDC, file=sys.stderr)