Skip to content

Commit 3f62f31

Browse files
partheagcf-owl-bot[bot]
parthea
and
gcf-owl-bot[bot]
authored
chore: update generated docs (#2381)
Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
1 parent 13a669a commit 3f62f31

File tree

42 files changed

+876
-187
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+876
-187
lines changed

‎docs/conf.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040

4141
# If your documentation needs a minimal Sphinx version, state it here.
4242
#
43-
# needs_sphinx = '1.0'
43+
needs_sphinx = "4.5.0"
4444

4545
# Add any Sphinx extension module names here, as strings. They can be
4646
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

‎gapic/ads-templates/docs/conf.py.j2

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ __version__ = "0.1.0"
2828
# -- General configuration ------------------------------------------------
2929

3030
# If your documentation needs a minimal Sphinx version, state it here.
31-
needs_sphinx = "4.0.1"
31+
needs_sphinx = "4.5.0"
3232

3333
# Add any Sphinx extension module names here, as strings. They can be
3434
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

‎gapic/templates/docs/_static/custom.css.j2

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,20 @@
1+
div#python2-eol {
2+
border-color: red;
3+
border-width: medium;
4+
}
5+
6+
/* Ensure minimum width for 'Parameters' / 'Returns' column */
17
dl.field-list > dt {
28
min-width: 100px
3-
}
9+
}
10+
11+
/* Insert space between methods for readability */
12+
dl.method {
13+
padding-top: 10px;
14+
padding-bottom: 10px
15+
}
16+
17+
/* Insert empty space between classes */
18+
dl.class {
19+
padding-bottom: 50px
20+
}

‎gapic/templates/docs/_templates/layout.html.j2

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
{% raw %}
2+
{% extends "!layout.html" %}
3+
{%- block content %}
4+
{%- if theme_fixed_sidebar|lower == 'true' %}
5+
<div class="document">
6+
{{ sidebar() }}
7+
{%- block document %}
8+
<div class="documentwrapper">
9+
{%- if render_sidebar %}
10+
<div class="bodywrapper">
11+
{%- endif %}
12+
13+
{%- block relbar_top %}
14+
{%- if theme_show_relbar_top|tobool %}
15+
<div class="related top">
16+
&nbsp;
17+
{{- rellink_markup () }}
18+
</div>
19+
{%- endif %}
20+
{% endblock %}
21+
22+
<div class="body" role="main">
23+
<div class="admonition" id="python2-eol">
24+
As of January 1, 2020 this library no longer supports Python 2 on the latest released version.
25+
Library versions released prior to that date will continue to be available. For more information please
26+
visit <a href="https://cloud.google.com/python/docs/python2-sunset/">Python 2 support on Google Cloud</a>.
27+
</div>
28+
{% block body %} {% endblock %}
29+
</div>
30+
31+
{%- block relbar_bottom %}
32+
{%- if theme_show_relbar_bottom|tobool %}
33+
<div class="related bottom">
34+
&nbsp;
35+
{{- rellink_markup () }}
36+
</div>
37+
{%- endif %}
38+
{% endblock %}
39+
40+
{%- if render_sidebar %}
41+
</div>
42+
{%- endif %}
43+
</div>
44+
{%- endblock %}
45+
<div class="clearer"></div>
46+
</div>
47+
{%- else %}
48+
{{ super() }}
49+
{%- endif %}
50+
{%- endblock %}
51+
{% endraw %}

‎gapic/templates/docs/conf.py.j2

Lines changed: 32 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,16 @@ import shlex
2323
# documentation root, use os.path.abspath to make it absolute, like shown here.
2424
sys.path.insert(0, os.path.abspath(".."))
2525

26-
__version__ = "0.1.0"
26+
# For plugins that can not read conf.py.
27+
# See also: https://github.com/docascode/sphinx-docfx-yaml/issues/85
28+
sys.path.insert(0, os.path.abspath("."))
29+
30+
__version__ = ""
2731

2832
# -- General configuration ------------------------------------------------
2933

3034
# If your documentation needs a minimal Sphinx version, state it here.
31-
needs_sphinx = "4.0.1"
35+
needs_sphinx = "4.5.0"
3236

3337
# Add any Sphinx extension module names here, as strings. They can be
3438
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -38,26 +42,25 @@ extensions = [
3842
"sphinx.ext.autosummary",
3943
"sphinx.ext.intersphinx",
4044
"sphinx.ext.coverage",
45+
"sphinx.ext.doctest",
4146
"sphinx.ext.napoleon",
4247
"sphinx.ext.todo",
4348
"sphinx.ext.viewcode",
49+
"recommonmark",
4450
]
4551

4652
# autodoc/autosummary flags
4753
autoclass_content = "both"
48-
autodoc_default_flags = ["members"]
54+
autodoc_default_options = {"members": True}
4955
autosummary_generate = True
5056

5157

5258
# Add any paths that contain templates here, relative to this directory.
5359
templates_path = ["_templates"]
5460

55-
# Allow markdown includes (so releases.md can include CHANGLEOG.md)
56-
# http://www.sphinx-doc.org/en/master/markdown.html
57-
source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
58-
5961
# The suffix(es) of source filenames.
6062
# You can specify multiple suffix as a list of string:
63+
# source_suffix = ['.rst', '.md']
6164
source_suffix = [".rst", ".md"]
6265

6366
# The encoding of source files.
@@ -68,8 +71,8 @@ root_doc = "index"
6871

6972
# General information about the project.
7073
project = u"{{ api.naming.warehouse_package_name }}"
71-
copyright = u"2023, Google, LLC"
72-
author = u"Google APIs" # TODO: autogenerate this bit
74+
copyright = u"2025, Google, LLC"
75+
author = u"Google APIs"
7376

7477
# The version info for the project you're documenting, acts as replacement for
7578
# |version| and |release|, also used in various other places throughout the
@@ -85,7 +88,7 @@ version = ".".join(release.split(".")[0:2])
8588
#
8689
# This is also used if you do content translation via gettext catalogs.
8790
# Usually you set "language" from the command line for these cases.
88-
language = 'en'
91+
language = None
8992

9093
# There are two options for replacing |today|: either, you set today to some
9194
# non-false value, then it is used:
@@ -95,7 +98,13 @@ language = 'en'
9598

9699
# List of patterns, relative to source directory, that match files and
97100
# directories to ignore when looking for source files.
98-
exclude_patterns = ["_build"]
101+
exclude_patterns = [
102+
"_build",
103+
"**/.nox/**/*",
104+
"samples/AUTHORING_GUIDE.md",
105+
"samples/CONTRIBUTING.md",
106+
"samples/snippets/README.rst",
107+
]
99108

100109
# The reST default role (used for this markup: `text`) to use for all
101110
# documents.
@@ -135,7 +144,7 @@ html_theme = "alabaster"
135144
# further. For a list of options available for each theme, see the
136145
# documentation.
137146
html_theme_options = {
138-
"description": "{{ api.naming.namespace|join(' ') }} Client Libraries for Python",
147+
"description": "{{ api.naming.namespace|join(' ') }} Client Libraries for {{ api.naming.warehouse_package_name }}",
139148
"github_user": "googleapis",
140149
"github_repo": "google-cloud-python",
141150
"github_banner": True,
@@ -298,7 +307,7 @@ man_pages = [
298307
(
299308
root_doc,
300309
"{{ api.naming.warehouse_package_name }}",
301-
u"{{ api.naming.long_name }} Documentation",
310+
"{{ api.naming.warehouse_package_name }} Documentation",
302311
[author],
303312
1,
304313
)
@@ -317,10 +326,10 @@ texinfo_documents = [
317326
(
318327
root_doc,
319328
"{{ api.naming.warehouse_package_name }}",
320-
u"{{ api.naming.warehouse_package_name }} Documentation",
329+
"{{ api.naming.warehouse_package_name }} Documentation",
321330
author,
322331
"{{ api.naming.warehouse_package_name }}",
323-
"GAPIC library for {{ api.naming.long_name }} API",
332+
"{{ api.naming.warehouse_package_name }} Library",
324333
"APIs",
325334
)
326335
]
@@ -340,14 +349,14 @@ texinfo_documents = [
340349

341350
# Example configuration for intersphinx: refer to the Python standard library.
342351
intersphinx_mapping = {
343-
"python": ("http://python.readthedocs.org/en/latest/", None),
344-
"gax": ("https://gax-python.readthedocs.org/en/latest/", None),
345-
"google-auth": ("https://google-auth.readthedocs.io/en/stable", None),
346-
"google-gax": ("https://gax-python.readthedocs.io/en/latest/", None),
347-
"google.api_core": ("https://googleapis.dev/python/google-api-core/latest/", None),
348-
"grpc": ("https://grpc.io/grpc/python/", None),
349-
"requests": ("http://requests.kennethreitz.org/en/stable/", None),
350-
"proto": ("https://proto-plus-python.readthedocs.io/en/stable", None),
352+
"python": ("https://python.readthedocs.org/en/latest/", None),
353+
"google-auth": ("https://googleapis.dev/python/google-auth/latest/", None),
354+
"google.api_core": (
355+
"https://googleapis.dev/python/google-api-core/latest/",
356+
None,
357+
),
358+
"grpc": ("https://grpc.github.io/grpc/python/", None),
359+
"proto-plus": ("https://proto-plus-python.readthedocs.io/en/latest/", None),
351360
"protobuf": ("https://googleapis.dev/python/protobuf/latest/", None),
352361
}
353362

‎gapic/templates/docs/index.rst.j2

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
.. include:: multiprocessing.rst
2+
3+
14
API Reference
25
-------------
36
.. toctree::

‎gapic/templates/docs/multiprocessing.rst.j2

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. note::
2+
3+
Because this client uses :mod:`grpc` library, it is safe to
4+
share instances across threads. In multiprocessing scenarios, the best
5+
practice is to create client instances *after* the invocation of
6+
:func:`os.fork` by :class:`multiprocessing.pool.Pool` or
7+
:class:`multiprocessing.Process`.

‎tests/integration/goldens/asset/docs/_static/custom.css

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,20 @@
1+
div#python2-eol {
2+
border-color: red;
3+
border-width: medium;
4+
}
5+
6+
/* Ensure minimum width for 'Parameters' / 'Returns' column */
17
dl.field-list > dt {
28
min-width: 100px
39
}
10+
11+
/* Insert space between methods for readability */
12+
dl.method {
13+
padding-top: 10px;
14+
padding-bottom: 10px
15+
}
16+
17+
/* Insert empty space between classes */
18+
dl.class {
19+
padding-bottom: 50px
20+
}

‎tests/integration/goldens/asset/docs/_templates/layout.html

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
2+
{% extends "!layout.html" %}
3+
{%- block content %}
4+
{%- if theme_fixed_sidebar|lower == 'true' %}
5+
<div class="document">
6+
{{ sidebar() }}
7+
{%- block document %}
8+
<div class="documentwrapper">
9+
{%- if render_sidebar %}
10+
<div class="bodywrapper">
11+
{%- endif %}
12+
13+
{%- block relbar_top %}
14+
{%- if theme_show_relbar_top|tobool %}
15+
<div class="related top">
16+
&nbsp;
17+
{{- rellink_markup () }}
18+
</div>
19+
{%- endif %}
20+
{% endblock %}
21+
22+
<div class="body" role="main">
23+
<div class="admonition" id="python2-eol">
24+
As of January 1, 2020 this library no longer supports Python 2 on the latest released version.
25+
Library versions released prior to that date will continue to be available. For more information please
26+
visit <a href="https://cloud.google.com/python/docs/python2-sunset/">Python 2 support on Google Cloud</a>.
27+
</div>
28+
{% block body %} {% endblock %}
29+
</div>
30+
31+
{%- block relbar_bottom %}
32+
{%- if theme_show_relbar_bottom|tobool %}
33+
<div class="related bottom">
34+
&nbsp;
35+
{{- rellink_markup () }}
36+
</div>
37+
{%- endif %}
38+
{% endblock %}
39+
40+
{%- if render_sidebar %}
41+
</div>
42+
{%- endif %}
43+
</div>
44+
{%- endblock %}
45+
<div class="clearer"></div>
46+
</div>
47+
{%- else %}
48+
{{ super() }}
49+
{%- endif %}
50+
{%- endblock %}

0 commit comments

Comments
 (0)