Skip to content

Commit 4d9f6a5

Browse files
tseavertseaver
authored
Prep datastore docs for repo split. (googleapis#5919)
- Move docs from 'docs/datastore' into 'datastore/docs' and leave symlink. - Harmonize / DRY 'datastore/README.rst' and 'datastore/docs/index.rst'. - Remove docs for GAPIC-generated bits (they aren't part of the surface). - Ensure that docs still build from top-level. Toward googleapis#5912.
1 parent 21ff713 commit 4d9f6a5

File tree

18 files changed

+90
-171
lines changed

18 files changed

+90
-171
lines changed

‎datastore/CHANGELOG.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727

2828
### Implementation changes
2929

30-
- Don't check 'exclude_from_indexes' for empty lists. (#4915)
30+
- Don't check `exclude_from_indexes` for empty lists. (#4915)
3131

3232
### Dependencies
3333

@@ -39,7 +39,7 @@
3939
- Re-enable lint for tests, remove usage of pylint (#4921)
4040
- Normalize all setup.py files (#4909)
4141
- Exercise datastore query result paging (#4905)
42-
- Pass '*session.posargs' through on command line for system tests. (#4904)
42+
- Pass `*session.posargs` through on command line for system tests. (#4904)
4343

4444
## 1.5.0
4545

‎datastore/README.rst‎

Lines changed: 60 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,78 @@
11
Python Client for Google Cloud Datastore
22
========================================
33

4-
Python idiomatic client for `Google Cloud Datastore`_
5-
6-
.. _Google Cloud Datastore: https://cloud.google.com/datastore/docs
7-
84
|pypi| |versions|
95

10-
- `Documentation`_
6+
`Google Cloud Datastore API`_ is a fully managed, schemaless database for
7+
storing non-relational data. Cloud Datastore automatically scales with your
8+
users and supports ACID transactions, high availability of reads and writes,
9+
strong consistency for reads and ancestor queries, and eventual consistency for
10+
all other queries.
1111

12-
.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/datastore/client.html
12+
- `Client Library Documentation`_
13+
- `Product Documentation`_
14+
15+
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-datastore.svg
16+
:target: https://pypi.org/project/google-cloud-datastore/
17+
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-datastore.svg
18+
:target: https://pypi.org/project/google-cloud-datastore/
19+
.. _Google Cloud Datastore API: https://cloud.google.com/datastore/docs
20+
.. _Product Documentation: https://cloud.google.com/datastore/docs
21+
.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/datastore/index.html
1322

1423
Quick Start
1524
-----------
1625

17-
.. code-block:: console
26+
In order to use this library, you first need to go through the following steps:
27+
28+
1. `Select or create a Cloud Platform project.`_
29+
2. `Enable billing for your project.`_
30+
3. `Enable the Google Cloud Datastore API.`_
31+
4. `Setup Authentication.`_
1832

19-
$ pip install --upgrade google-cloud-datastore
33+
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
34+
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
35+
.. _Enable the Google Cloud Datastore API.: https://cloud.google.com/datastore
36+
.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
2037

21-
For more information on setting up your Python development environment,
22-
such as installing ``pip`` and ``virtualenv`` on your system, please refer
23-
to `Python Development Environment Setup Guide`_ for Google Cloud Platform.
38+
Installation
39+
~~~~~~~~~~~~
2440

25-
.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
41+
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
42+
create isolated Python environments. The basic problem it addresses is one of
43+
dependencies and versions, and indirectly permissions.
2644

27-
Authentication
28-
--------------
45+
With `virtualenv`_, it's possible to install this library without needing system
46+
install permissions, and without clashing with the installed system
47+
dependencies.
2948

30-
With ``google-cloud-python`` we try to make authentication as painless as
31-
possible. Check out the `Authentication section`_ in our documentation to
32-
learn more. You may also find the `authentication document`_ shared by all
33-
the ``google-cloud-*`` libraries to be helpful.
49+
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
3450

35-
.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
36-
.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication
3751

38-
Using the API
39-
-------------
52+
Mac/Linux
53+
^^^^^^^^^
4054

41-
Google `Cloud Datastore`_ (`Datastore API docs`_) is a fully managed,
42-
schemaless database for storing non-relational data. Cloud Datastore
43-
automatically scales with your users and supports ACID transactions, high
44-
availability of reads and writes, strong consistency for reads and ancestor
45-
queries, and eventual consistency for all other queries.
55+
.. code-block:: console
56+
57+
pip install virtualenv
58+
virtualenv <your-env>
59+
source <your-env>/bin/activate
60+
<your-env>/bin/pip install google-cloud-datastore
4661
47-
.. _Cloud Datastore: https://cloud.google.com/datastore/docs
48-
.. _Datastore API docs: https://cloud.google.com/datastore/docs/
4962
50-
See the ``google-cloud-python`` API `datastore documentation`_ to learn how to
51-
interact with the Cloud Datastore using this Client Library.
63+
Windows
64+
^^^^^^^
5265

53-
.. _datastore documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/datastore/client.html
66+
.. code-block:: console
5467
55-
See the `official Google Cloud Datastore documentation`_ for more details on
56-
how to activate Cloud Datastore for your project.
68+
pip install virtualenv
69+
virtualenv <your-env>
70+
<your-env>\Scripts\activate
71+
<your-env>\Scripts\pip.exe install google-cloud-datastore
5772
58-
.. _official Google Cloud Datastore documentation: https://cloud.google.com/datastore/docs/activate
73+
74+
Example Usage
75+
~~~~~~~~~~~~~
5976

6077
.. code:: python
6178
@@ -72,9 +89,12 @@ how to activate Cloud Datastore for your project.
7289
client.put(entity)
7390
# Then get by key for this entity
7491
result = client.get(key)
75-
print result
92+
print(result)
7693
77-
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-datastore.svg
78-
:target: https://pypi.org/project/google-cloud-datastore/
79-
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-datastore.svg
80-
:target: https://pypi.org/project/google-cloud-datastore/
94+
Next Steps
95+
~~~~~~~~~~
96+
97+
- Read the `Client Library Documentation`_ for Google Cloud Datastore API
98+
API to see other available methods on the client.
99+
- Read the `Product documentation`_ to learn
100+
more about the product and see How-to Guides.

docs/datastore/batches.rst renamed to datastore/docs/batches.rst

File renamed without changes.

‎datastore/docs/changelog.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../CHANGELOG.md

docs/datastore/client.rst renamed to datastore/docs/client.rst

File renamed without changes.

‎datastore/docs/conf.py‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
extensions = [
3434
'sphinx.ext.autodoc',
3535
'sphinx.ext.autosummary',
36+
'sphinx.ext.doctest',
3637
'sphinx.ext.intersphinx',
3738
'sphinx.ext.coverage',
3839
'sphinx.ext.napoleon',
@@ -47,6 +48,12 @@
4748
# Add any paths that contain templates here, relative to this directory.
4849
templates_path = ['_templates']
4950

51+
# Allow markdown includes (so releases.md can include CHANGLEOG.md)
52+
# http://www.sphinx-doc.org/en/master/markdown.html
53+
source_parsers = {
54+
'.md': 'recommonmark.parser.CommonMarkParser',
55+
}
56+
5057
# The suffix(es) of source filenames.
5158
# You can specify multiple suffix as a list of string:
5259
# source_suffix = ['.rst', '.md']
@@ -120,7 +127,7 @@
120127

121128
# The theme to use for HTML and HTML Help pages. See the documentation for
122129
# a list of builtin themes.
123-
html_theme = 'sphinx_rtd_theme'
130+
html_theme = 'alabaster'
124131

125132
# Theme options are theme-specific and customize the look and feel of a theme
126133
# further. For a list of options available for each theme, see the

docs/datastore/entities.rst renamed to datastore/docs/entities.rst

File renamed without changes.

‎datastore/docs/gapic/v1/api.rst‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎datastore/docs/gapic/v1/types.rst‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

docs/datastore/helpers.rst renamed to datastore/docs/helpers.rst

File renamed without changes.

0 commit comments

Comments
 (0)