Skip to content

Commit 9224885

Browse files
bshafferbshaffer
committed
feat(docs): publish Client libraries help to python reference documentation
1 parent 2a3458c commit 9224885

File tree

6 files changed

+251
-0
lines changed

6 files changed

+251
-0
lines changed

‎packages/help/.repo-metadata.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"name": "help",
3+
"name_pretty": "Client libraries help",
4+
"client_documentation": "https://cloud.google.com/python/docs/reference/help/latest",
5+
"language": "python",
6+
"library_type": "OTHER",
7+
"repo": "googleapis/google-cloud-python",
8+
"distribution_name": "help",
9+
"codeowner_team": "@googleapis/cloud-sdk-python-team"
10+
}

‎packages/help/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Google Cloud Python Help
2+
3+
Client libraries help documentation for common support issues and general information.

‎packages/help/docfx_helper.py‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# https://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
import os
16+
import pathlib
17+
import shutil
18+
import sys
19+
import yaml
20+
import pypandoc
21+
22+
def build_docfx(current_dir, repo_root, docs_map):
23+
current_dir = pathlib.Path(current_dir)
24+
repo_root = pathlib.Path(repo_root)
25+
output_dir = current_dir / "docs" / "_build"
26+
27+
if output_dir.exists():
28+
shutil.rmtree(output_dir)
29+
output_dir.mkdir(parents=True)
30+
31+
# Ensure pandoc is available (pypandoc will download it if not found in PATH)
32+
try:
33+
pypandoc.get_pandoc_version()
34+
except OSError:
35+
print("Pandoc not found. Downloading...")
36+
pypandoc.download_pandoc()
37+
38+
toc = []
39+
40+
for title, source in docs_map.items():
41+
source_path = pathlib.Path(source)
42+
if not source_path.is_absolute():
43+
source_path = current_dir / source_path
44+
45+
filename = source_path.name
46+
47+
if filename.endswith(".rst"):
48+
target_filename = filename.replace(".rst", ".md")
49+
print(f"Converting {filename} -> {target_filename} using pandoc")
50+
if source_path.exists():
51+
# Use pandoc to convert RST to GFM (GitHub Flavored Markdown)
52+
output = pypandoc.convert_file(
53+
str(source_path),
54+
'gfm',
55+
format='rst'
56+
)
57+
(output_dir / target_filename).write_text(output)
58+
else:
59+
print(f"Warning: Source {source_path} not found.")
60+
(output_dir / target_filename).write_text(f"# {title}\n\nContent missing.")
61+
href = target_filename
62+
else:
63+
print(f"Copying {filename}")
64+
if source_path.exists():
65+
shutil.copy(source_path, output_dir / filename)
66+
else:
67+
print(f"Warning: Source {source_path} not found.")
68+
(output_dir / filename).write_text(f"# {title}\n\nContent missing.")
69+
href = filename
70+
71+
toc.append({"name": title, "href": href})
72+
73+
# Write toc.yaml
74+
toc_path = output_dir / "toc.yaml"
75+
with open(toc_path, "w") as f:
76+
yaml.dump(toc, f, default_flow_style=False)
77+
78+
print(f"DocFX build complete in {output_dir}")
79+
print(f"Generated TOC: {toc}")
80+
81+
if __name__ == "__main__":
82+
# Simple argument parsing: current_dir, repo_root, then pairs of Title,Source
83+
curr = sys.argv[1]
84+
root = sys.argv[2]
85+
d_map = {}
86+
for i in range(3, len(sys.argv), 2):
87+
d_map[sys.argv[i]] = sys.argv[i+1]
88+
89+
build_docfx(curr, root, d_map)

‎packages/help/help/version.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Copyright 2022 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
__version__ = "1.0.0"
16+
17+
# {x-release-please-start-date}
18+
__release_date__ = "2026-04-07"
19+
# {x-release-please-end}

‎packages/help/noxfile.py‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Copyright 2026 Google LLC
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# https://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software/
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
from __future__ import absolute_import
18+
19+
import pathlib
20+
import nox
21+
22+
DEFAULT_PYTHON_VERSION = "3.14"
23+
CURRENT_DIRECTORY = pathlib.Path(__file__).parent.absolute()
24+
REPO_ROOT = CURRENT_DIRECTORY.parent.parent
25+
26+
# Hardcoded dictionary of documentation files.
27+
# Format: {"Display Title": "filename.md" or absolute path}
28+
DOCS_MAP = {
29+
"Getting started": str(REPO_ROOT / "README.rst"),
30+
}
31+
32+
nox.options.sessions = [
33+
"lint",
34+
"docfx",
35+
]
36+
37+
# Error if a python version is missing
38+
nox.options.error_on_missing_interpreters = True
39+
40+
@nox.session(python=DEFAULT_PYTHON_VERSION)
41+
def lint(session):
42+
"""Run linters."""
43+
session.install("ruff")
44+
session.run("ruff", "check", ".")
45+
46+
@nox.session(python="3.10")
47+
def docfx(session):
48+
"""Build the docfx yaml files for this library."""
49+
session.install("PyYAML", "pypandoc")
50+
51+
# Construct arguments for the helper script
52+
args = [str(CURRENT_DIRECTORY), str(REPO_ROOT)]
53+
for title, source in DOCS_MAP.items():
54+
args.extend([title, str(source)])
55+
56+
session.run("python", "docfx_helper.py", *args)

‎packages/help/setup.py‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
16+
import io
17+
import os
18+
19+
import setuptools
20+
21+
# Package metadata.
22+
23+
name = "help"
24+
description = "Client libraries help documentation"
25+
release_status = "Development Status :: 5 - Production/Stable"
26+
dependencies = []
27+
28+
# Setup boilerplate below this line.
29+
30+
package_root = os.path.abspath(os.path.dirname(__file__))
31+
32+
readme_filename = os.path.join(package_root, "README.md")
33+
with io.open(readme_filename, encoding="utf-8") as readme_file:
34+
readme = readme_file.read()
35+
36+
version = {}
37+
with open(os.path.join(package_root, "help/version.py")) as fp:
38+
exec(fp.read(), version)
39+
version_id = version["__version__"]
40+
41+
setuptools.setup(
42+
name=name,
43+
version=version_id,
44+
description=description,
45+
long_description=readme,
46+
long_description_content_type="text/markdown",
47+
author="Google LLC",
48+
author_email="cloud-sdk@google.com",
49+
license="Apache 2.0",
50+
url="https://github.com/googleapis/google-cloud-python/tree/main/packages/help",
51+
project_urls={
52+
"Source": "https://github.com/googleapis/google-cloud-python/tree/main/packages/help",
53+
"Changelog": "https://github.com/googleapis/google-cloud-python/tree/main/packages/help/CHANGELOG.md",
54+
"Issues": "https://github.com/googleapis/google-cloud-python/issues",
55+
},
56+
classifiers=[
57+
release_status,
58+
"Intended Audience :: Developers",
59+
"Programming Language :: Python",
60+
"Programming Language :: Python :: 3",
61+
"Programming Language :: Python :: 3.10",
62+
"Programming Language :: Python :: 3.11",
63+
"Programming Language :: Python :: 3.12",
64+
"Programming Language :: Python :: 3.13",
65+
"Programming Language :: Python :: 3.14",
66+
"Operating System :: OS Independent",
67+
"Topic :: Internet",
68+
],
69+
install_requires=dependencies,
70+
python_requires=">=3.10",
71+
include_package_data=True,
72+
zip_safe=False,
73+
packages=["help"],
74+
)

0 commit comments

Comments
 (0)