Docs build in google-ai-generativelanguage fails

[parthea]

I had to manually fix a google-cloud-python PR that had a comment looking like this:

        Returns:
            google.ai.generativelanguage_v1beta3.types.Permission:
                Permission resource grants user,
                group or the rest of the world access to
                the PaLM API resource (e.g. a tuned
                model, file).
                A role is a collection of permitted
                operations that allows users to perform
                specific actions on PaLM API resources.
                To make them available to users, groups,
                or service accounts, you assign roles.
                When you assign a role, you grant
                permissions that the role contains.
                There are three concentric roles. Each
                role is a superset of the previous
                role's permitted operations:
                 - reader can use the resource (e.g.
                  tuned model) for inference
                 - writer has reader's permissions and
                  additionally can edit and share
                 - owner has writer's permissions and
                  additionally can delete

The issue is that sphinx does not expect a blank space before a list item. Sphinx expects to see

        Returns:
            google.ai.generativelanguage_v1beta3.types.Permission:
                Permission resource grants user,
                group or the rest of the world access to
                the PaLM API resource (e.g. a tuned
                model, file).
                A role is a collection of permitted
                operations that allows users to perform
                specific actions on PaLM API resources.
                To make them available to users, groups,
                or service accounts, you assign roles.
                When you assign a role, you grant
                permissions that the role contains.
                There are three concentric roles. Each
                role is a superset of the previous
                role's permitted operations:
                - reader can use the resource (e.g.
                  tuned model) for inference
                - writer has reader's permissions and
                  additionally can edit and share
                - owner has writer's permissions and
                  additionally can delete

We should add this as a test here and also consider proposing an update to AIPs to check if the API protos could follow this convention as well.

See build log here which includes the full stack trace from https://github.com/googleapis/google-cloud-python/pull/11670

[vchudnov-g]

You mention blank lines, but the code snippets in your description and your fix don't deal with blank lines, just with out-denting the list items. At the same time, the build log you reference talks about the error being triggered by a lack of a blank line after the indented list items.

Is the issue that when the list items are indented, they need to be followed by a blank line, so it's easier to not indent them if possible?

[ohmayr]

I agree with @vchudnov-g that we're not dealing with blank lines in the fix and it only includes outdenting the bullet points even though the build logs have the following error:

Bullet list ends without a blank line; unexpected unindent.

@parthea we'll need some more clarification here.

[parthea]

The error mentions Bullet list ends without a blank line; unexpected unindent. but my comment doesn't mention blank line.

The issue is that sphinx does not expect a blank space before a list item.

Perhaps the error from sphinx is misleading. Please see my comment The issue is that sphinx does not expect a blank space before a list item.

[parthea]

Capturing another docs issue with google-ai-generativelanguage

See https://github.com/googleapis/googleapis/blob/b54255c0ad0a432c29ae3e15fd79a53c5ebc03b1/google/ai/generativelanguage/v1beta/retriever.proto#L74-L75 where there is an asterisk character which is not surrounded by backticks or escaped.

This caused the docs build to fail with

sphinx.errors.SphinxWarning: /usr/local/google/home/partheniou/git/google-cloud-python/packages/google-ai-generativelanguage/google/ai/generativelanguage_v1beta/types/retriever.py:docstring of google.ai.generativelanguage_v1beta.types.retriever.Document:6:Inline emphasis start-string without end-string.

Warning, treated as error:
/usr/local/google/home/partheniou/git/google-cloud-python/packages/google-ai-generativelanguage/google/ai/generativelanguage_v1beta/types/retriever.py:docstring of google.ai.generativelanguage_v1beta.types.retriever.Document:6:Inline emphasis start-string without end-string.

Instead of

  // Immutable. Identifier. The `Document` resource name. The ID (name excluding
  // the "corpora/*/documents/" prefix) can contain up to 40 characters that are

It should be

  // Immutable. Identifier. The `Document` resource name. The ID (name excluding
  // the `corpora/*/documents/` prefix) can contain up to 40 characters that are

See https://github.com/googleapis/google-cloud-python/actions/runs/7147914046/job/19468207013?pr=12106

We should add a linter rule to check for unsupported formatting in proto comments via https://github.com/googleapis/api-linter .