Open parthea opened 1 year ago
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?
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.
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.
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 .
I had to manually fix a
google-cloud-python
PR that had a comment looking like this:The issue is that sphinx does not expect a blank space before a list item. Sphinx expects to see
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