Repository navigation
Interleave doctest examples w/ API ref docs. #1141
Description
Related to #1102
I just tried to walk a group of people through gcloud.pubsub, and of the few who found the docs under "Pubsub usage", almost everyone was frustrated by the examples being there rather than next to the method they were interested in. They couldn't find the specific thing they wanted quickly, whereas finding the right methods was pretty straight forward -- but then example code was hidden in a big long (and separate) page.
Ideally we would:
- Move all the usage examples to live next to the methods they describe
- Remove the pubsub-usage.rst file
- Have test coverage of those docstring examples
(ie, https://googlecloudplatform.github.io/gcloud-python/stable/pubsub-topic.html has no example code snippets)
Activity
dhermes commentedon Sep 16, 2015
FWIW I've never been a big fan of the
*-usagedocs.IIRC you encouraged us to create them after @tseaver started the very first one for Pub/Sub (datastore and storage don't really have them).
jgeewax commentedon Sep 16, 2015
Yes, the goal of the usage docs was "let's define the actions and the API surface" and debate the usage in those docs rather than in code that implements them -- which I still think we should do with new APIs...
The goal wasn't to hide examples in there and take them out of docstrings... Sorry if that was confusing.
dhermes commentedon Sep 16, 2015
We never took them out, just for those packages they never went in as a result. The process was never really explicit in either direction.
dhermes commentedon Sep 16, 2015
Also @jgeewax third item relies on #212 being done
tseaver commentedon Sep 23, 2015
Making the example snippets testable requires being able to tie them to specific
testsetupandtestcleanupgroups.My inclination would be not to put the examples in the docstrings themselves, but to interleave them with the docstring-generated API reference docs. This would require making the API reference less DRY, as we would need to explicitly name each method (to pull in its docstring) before the example. In exchange, we would gain some benefits:
testsetupandtestcleanupgroups without trying to sync them between docstrings and the Sphinx source.dhermes commentedon Sep 24, 2015
I'd like to make that such a change would include #714 (e.g. an automated way to make sure all public functions, classes, methods, constants, or otherwise, are documented)
[-]Add examples to pubsub methods[/-][+]Interleave doctest examples w/ API ref docs. [/+]theacodes commentedon Aug 22, 2016
It seems that we currently have a lot of usage snippets that are untested included in the docs. This is really unacceptable. I'd vote that until #1744 (testing for snippets) is resolved, that you guys instead link to the docs on cloud.google.com (where applicable) where samples are tested. Some products haven't been updated to use gcloud-python, but that gap should be closing this quarter for Datastore, Pub/Sub, Logging, BigQuery, and Storage.
We can't be putting untested samples in front of users.
/cc @omaray
tseaver commentedon Aug 25, 2016
#2154 is really where this should be tracked as an ongoing issue.
fix: alembic column rename (#1141)
feat: add `--no_query_cache` option to `%%bigquery` magics to disable…