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

Improve autodocs for top-level package names. #882

Merged
merged 2 commits into from
May 18, 2015
Merged

Improve autodocs for top-level package names. #882

merged 2 commits into from
May 18, 2015

Conversation

tseaver
Copy link
Contributor

@tseaver tseaver commented May 14, 2015

  • Drop the __init__ from them.
  • Include the ones imported from _implicit_environ'

Fixes #845.

- Drop the '__init__' from them.
- Include the ones imported from '_implicit_environ'.

Fixes #845.
@tseaver tseaver added api: datastore Issues related to the Datastore API. docs api: storage Issues related to the Cloud Storage API. api: pubsub Issues related to the Pub/Sub API. labels May 14, 2015
@googlebot googlebot added the cla: yes This human has signed the Contributor License Agreement. label May 14, 2015
@coveralls
Copy link

Coverage Status

Coverage remained the same at 100.0% when pulling 22e4c63 on tseaver:845-document__implicit_environ into 9c4867a on GoogleCloudPlatform:master.

@dhermes
Copy link
Contributor

dhermes commented May 14, 2015

I've checked out this branch and built the docs. All looks good, can you fix the docstring for datastore.set_defaults so the bullets render correctly? Use * instead of - for Sphinx.

@dhermes
Copy link
Contributor

dhermes commented May 14, 2015

Also a concern, this is very manual. How will we make sure new methods in __init__ get added to the docs?

@tseaver
Copy link
Contributor Author

tseaver commented May 14, 2015

fbba1c4 fixes the bullet rendering (not *, but a leading blank line, was required).

WRT manual config: We can't have best of all worlds for members imported into the base package:

  • Adding :imported-members: would pick up all the imports.
  • Adding just the ones we want to __all__ would make using the others look unsupported.

The real fix would be to move those implementations into the base package, and have them just tweak the defaults object in _implicit_environ.

@coveralls
Copy link

Coverage Status

Coverage remained the same at 100.0% when pulling fbba1c4 on tseaver:845-document__implicit_environ into 9c4867a on GoogleCloudPlatform:master.

@dhermes
Copy link
Contributor

dhermes commented May 14, 2015

I don't think the circular import gymnastics is worth it for this somewhat minor nit. Proceed: LGTM.

tseaver added a commit that referenced this pull request May 18, 2015
Improve autodocs for top-level package names.
@tseaver tseaver merged commit 6bc4e02 into googleapis:master May 18, 2015
@tseaver tseaver deleted the 845-document__implicit_environ branch May 18, 2015 18:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
api: datastore Issues related to the Datastore API. api: pubsub Issues related to the Pub/Sub API. api: storage Issues related to the Cloud Storage API. cla: yes This human has signed the Contributor License Agreement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Sphinx needs to document methods from _implicit_environ
4 participants