Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Issue with generated docstring in Artifact Registry V1 #998

Closed
parthea opened this issue Sep 24, 2021 · 2 comments
Closed

Issue with generated docstring in Artifact Registry V1 #998

parthea opened this issue Sep 24, 2021 · 2 comments
Assignees
Labels
priority: p2 Moderately-important priority. Fix may not be included in next release. type: bug Error or flaw in code with unintended results or allowing sub-optimal usage patterns.

Comments

@parthea
Copy link
Contributor

parthea commented Sep 24, 2021

There is a sphinx warning when generating the docs for Artifact Registry V1.

The source proto here, has the following comment:

// DockerImage represents a docker artifact.
// The following fields are returned as untyped metadata in the Version
// resource, using camelcase keys (i.e. metadata.imageSizeBytes):
//   - imageSizeBytes
//   - mediaType
//   - buildTime

The docstring that is generated based on the above code looks incorrectly formatted. See below:

    r"""DockerImage represents a docker artifact.
    The following fields are returned as untyped metadata in the
    Version resource, using camelcase keys (i.e.
    metadata.imageSizeBytes):   - imageSizeBytes
      - mediaType
      - buildTime

Sphinx is reporting this warning, which is causing our docs build to fail in googleapis/python-artifact-registry#80 since we're treating warnings as errors.

sphinx.errors.SphinxWarning: /usr/local/google/home/partheniou/python-artifact-registry/google/cloud/artifactregistry_v1/types/artifact.py:docstring of google.cloud.artifactregistry_v1.types.artifact.DockerImage:5:Unexpected indentation.

Warning, treated as error:
/usr/local/google/home/partheniou/python-artifact-registry/google/cloud/artifactregistry_v1/types/artifact.py:docstring of google.cloud.artifactregistry_v1.types.artifact.DockerImage:5:Unexpected indentation.
nox > Command sphinx-build -W -T -N -b html -d docs/_build/doctrees/ docs/ docs/_build/html/ failed with exit code 2
nox > Session docs failed.

I found that the following docstring would not cause the sphinx build to fail so I've added a workaround in owlbot.py in googleapis/python-artifact-registry#80 to allow the PR to be merged.

    r"""DockerImage represents a docker artifact.
    The following fields are returned as untyped metadata in the
    Version resource, using camelcase keys (i.e.
    metadata.imageSizeBytes):

      - imageSizeBytes
      - mediaType
      - buildTime
@parthea parthea added type: bug Error or flaw in code with unintended results or allowing sub-optimal usage patterns. priority: p2 Moderately-important priority. Fix may not be included in next release. labels Sep 24, 2021
@parthea parthea self-assigned this Oct 13, 2021
@parthea
Copy link
Contributor Author

parthea commented Oct 19, 2021

Fix proposed in internal cl/404229788

@parthea
Copy link
Contributor Author

parthea commented Oct 19, 2021

Resolved with cl/404229788

@parthea parthea closed this as completed Oct 19, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
priority: p2 Moderately-important priority. Fix may not be included in next release. type: bug Error or flaw in code with unintended results or allowing sub-optimal usage patterns.
Projects
None yet
Development

No branches or pull requests

1 participant