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

Fix word-break in documentation #230

Closed
dylancaponi opened this issue Oct 29, 2020 · 4 comments
Closed

Fix word-break in documentation #230

dylancaponi opened this issue Oct 29, 2020 · 4 comments
Labels
api: pubsub Issues related to the googleapis/python-pubsub API. external This issue is blocked on a bug with the actual product. type: docs Improvement to the documentation for an API.

Comments

@dylancaponi
Copy link

dylancaponi commented Oct 29, 2020

Badly formatted sections of documentation where word-break causes the docs to be illegible. See screenshot examples below. Possibly expanding margins or turning off word-break for those elements could fix the problem.

Environment details

  • OS type and version: macOS Mojave 10.14.6
  • Browser: Chrome Version 86.0.4240.111 and Brave_ Version 1.16.68 Chromium
  • Resolution: 1080p
  • Python version: python --version n/a
  • pip version: pip --version n/a
  • google-cloud-pubsub version: pip show google-cloud-pubsub n/a

Steps to reproduce

  1. Go to: https://googleapis.dev/python/pubsub/latest/publisher/api/client.html?highlight=publish#google.cloud.pubsub_v1.publisher.client.Client.publish
  2. Search for get_topic( on page.

Normal:
image

Turn word break off:
image

Better but still not quite right:
image

Another example of difficult to read formatting:
image

Code example

In inspector you can turn on and off word-break: break-word; for Return type: and see how the formatting improves.

Stack trace

n/a

@product-auto-label product-auto-label bot added the api: pubsub Issues related to the googleapis/python-pubsub API. label Oct 29, 2020
@meredithslota meredithslota added external This issue is blocked on a bug with the actual product. type: docs Improvement to the documentation for an API. labels Oct 29, 2020
@plamut
Copy link
Contributor

plamut commented Jan 16, 2021

From what I can see, this has been (somewhat) addressed in the code generator, it sets the minimum width of the problematic column to 100px. Not a perfect fix, but it does improve readability significantly.

The changes will be included the next time we regenerate the generated parts of the library.

@dylancaponi
Copy link
Author

@plamut Thanks! What triggers a regeneration? I am still experiencing this issue.

@plamut
Copy link
Contributor

plamut commented Mar 5, 2021

@dylancaponi The autogenerated part of the library is re-generated every now and then, either because of external changes such as new type definitions, or because the hand-written layer needs to make some adjustments.

I generated the docs locally and the rendering seems fine, thus I'd say the docs at googleapis.dev/python/pubsub/latest/ have not been updated yet for some reason.

@anguillanneuf Do you have insight into the docs pipeline? What needs to be done to update them?
(I thought this is an automatic process every time a new client release is made)

@anguillanneuf
Copy link
Contributor

It looks like your PR #297 picked up changes from synthtool googleapis/synthtool#884, the published docs should reflect local changes with the next release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
api: pubsub Issues related to the googleapis/python-pubsub API. external This issue is blocked on a bug with the actual product. type: docs Improvement to the documentation for an API.
Projects
None yet
Development

No branches or pull requests

4 participants