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.

Sign up for GitHub

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

Jump to bottom

enum classes are missing docstrings #625

Closed
tswast opened this issue Sep 30, 2020 · 3 comments · Fixed by #714
Closed

enum classes are missing docstrings #625

tswast opened this issue Sep 30, 2020 · 3 comments · Fixed by #714
Assignees
@busunkim96
Labels
priority: p3 Desirable enhancement or fix. May not be included in next release. type: docs Improvement to the documentation for an API.

Comments

@tswast
Copy link

tswast commented Sep 30, 2020

googleapis/python-bigquery#278 (comment)

Ideally, there would be a docstring for each enum showing all the available values. This is a regression from the monolith generator.
@tswast tswast mentioned this issue Sep 30, 2020
Merged
3 tasks
@software-dov
Copy link
Contributor

Just curious, but is a docstring necessary for autogenerated documentation that's derived from the docstrings? Because it's easy to just...look at the values.

@software-dov software-dov added priority: p3 Desirable enhancement or fix. May not be included in next release. type: docs Improvement to the documentation for an API. labels Sep 30, 2020
@tswast
Copy link
Author

tswast commented Oct 27, 2020

Docstring isn't 100% necessary, but it would be good to show the values in the docs themselve. Having to click "view source" is a regression.

@busunkim96 busunkim96 mentioned this issue Dec 21, 2020
Merged
@busunkim96
Copy link
Contributor

Looks like adding undoc-members to types.rst fixes this. Change pending in #714.

image

@busunkim96 busunkim96 self-assigned this Dec 21, 2020
busunkim96 added a commit that referenced this issue Dec 22, 2020
@busunkim96
fix: fix sphinx identifiers (#714)
39be474 
Cross-references like `~.ImageAnnotatorClient` don't always work correctly with sphinx. This PR changes the `sphinx()` method to always produce a full path like `google.cloud.vision_v1.ImageAnnotatorClient`. 

Also some other smaller changes:
- Generate a separate `.rst` page for each service, which improves readability for APIs that have (1) a lot of services or (2) a lot of methods in a service. `services.rst` acts as an index page instead.
- Add pagers to the generated docs
- Use `undoc-members` to list enum attributes in generated docs (fixes #625) 
- Add newlines after bulleted lists by removing `nl=False`. Fixes #604 
- Add a 'docs' session to the templated `noxfile.py` so folks using the self-service model can have generated docs.
- Fix reference to LRO result type in `Returns:`
- Fix `{@api.name}` reference in the `from_service_account..`. methods  to reference the client type instead
- Remove `:class:` notation when specifying types for attributes (sphinx doesn't need it to create a link)
gcf-merge-on-green bot pushed a commit that referenced this issue Dec 22, 2020
@release-please
chore: release 0.39.0 (#719)
f646767 
🤖 I have created a release \*beep\* \*boop\* 
---
## [0.39.0](https://www.github.com/googleapis/gapic-generator-python/compare/v0.38.0...v0.39.0) (2020-12-22)


### Features

* allow warehouse name to be customized ([#717](https://www.github.com/googleapis/gapic-generator-python/issues/717)) ([7c185e8](https://www.github.com/googleapis/gapic-generator-python/commit/7c185e87cb4252b1f99ed121515814595f9492c4)), closes [#605](https://www.github.com/googleapis/gapic-generator-python/issues/605)


### Bug Fixes

* fix sphinx identifiers ([#714](https://www.github.com/googleapis/gapic-generator-python/issues/714)) ([39be474](https://www.github.com/googleapis/gapic-generator-python/commit/39be474b4419dfa521ef51927fd36dbf257d68e3)), closes [#625](https://www.github.com/googleapis/gapic-generator-python/issues/625) [#604](https://www.github.com/googleapis/gapic-generator-python/issues/604)
---


This PR was generated with [Release Please](https://github.com/googleapis/release-please).
@busunkim96 busunkim96 mentioned this issue Jan 6, 2021
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@busunkim96 busunkim96

Labels
priority: p3 Desirable enhancement or fix. May not be included in next release. type: docs Improvement to the documentation for an API.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

fix: fix sphinx identifiers googleapis/gapic-generator-python
3 participants
@tswast @software-dov @busunkim96