From aa32b157279e16a2f5ba4d4cd7aef431672143b9 Mon Sep 17 00:00:00 2001 From: Bo Xu Date: Fri, 3 Apr 2020 17:37:34 -0700 Subject: [PATCH 1/3] Update documentations and related configs --- README.md | 9 ++------- requirements.bazel.txt | 5 +---- setup.py | 3 --- 3 files changed, 3 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index dc1d902e..68548358 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,7 @@ GCP. Once you have the API key, simply add the following line to your code. dc.set_api_key('YOUR-API-KEY') For more detail on getting started with the API, please visit -[Getting Started](https://datacommons.readthedocs.io/en/latest/started.html). - -After you're ready to use the API, you can refer to `datacommons/examples` for -examples on how to use this package to perform various tasks. More tutorials and -documentation can be found at our -[readthedocs](https://datacommons.readthedocs.io/en/latest/)! +[Getting Started](http://docs.datacommons.org/api/). ## About Data Commons @@ -35,7 +30,7 @@ Apache 2.0 ## Development -The Python Client API currently supports `python>=3.6`. We use +The Python Client API currently supports `python>=2.7`. We use [bazel](https://bazel.build/) as our build system. To test, first install bazel then run the following: diff --git a/requirements.bazel.txt b/requirements.bazel.txt index ec041926..43831732 100644 --- a/requirements.bazel.txt +++ b/requirements.bazel.txt @@ -1,6 +1,3 @@ six mock -httplib2 -sphinx -sphinxcontrib-napoleon -sphinx_rtd_theme \ No newline at end of file +httplib2 \ No newline at end of file diff --git a/setup.py b/setup.py index 52a9e3a2..554b1e16 100644 --- a/setup.py +++ b/setup.py @@ -30,9 +30,6 @@ REQUIRED = [ 'six', 'httplib2', - 'sphinx', - 'sphinxcontrib-napoleon', - 'sphinx_rtd_theme', ] PACKAGES = ['datacommons'] From 1d41e3fd239f1cdaa3fa72dfc83880838f501e48 Mon Sep 17 00:00:00 2001 From: Bo Xu Date: Fri, 3 Apr 2020 17:38:42 -0700 Subject: [PATCH 2/3] Remove docs folder --- docs/Makefile | 20 --- docs/README.md | 31 ---- docs/make.bat | 35 ----- docs/source/_autosummary/datacommons.core.rst | 13 -- .../_autosummary/datacommons.places.rst | 11 -- .../_autosummary/datacommons.populations.rst | 14 -- .../source/_autosummary/datacommons.query.rst | 11 -- .../source/_autosummary/datacommons.utils.rst | 13 -- .../datacommons.core.get_property_labels.rst | 6 - .../datacommons.core.get_property_values.rst | 6 - .../datacommons.core.get_triples.rst | 6 - .../datacommons.places.get_places_in.rst | 6 - ...tacommons.populations.get_observations.rst | 6 - .../datacommons.populations.get_place_obs.rst | 6 - .../datacommons.populations.get_pop_obs.rst | 6 - ...atacommons.populations.get_populations.rst | 6 - .../datacommons.query.query.rst | 6 - .../datacommons.utils.clean_frame.rst | 6 - .../datacommons.utils.flatten_frame.rst | 6 - .../datacommons.utils.set_api_key.rst | 6 - docs/source/_static/theme_overrides.css | 10 -- docs/source/_templates/layout.html | 4 - docs/source/conf.py | 75 --------- docs/source/data_model.rst | 144 ------------------ docs/source/index.rst | 83 ---------- docs/source/modules.rst | 11 -- docs/source/started.rst | 102 ------------- docs/source/tutorials.rst | 31 ---- 28 files changed, 680 deletions(-) delete mode 100644 docs/Makefile delete mode 100644 docs/README.md delete mode 100644 docs/make.bat delete mode 100644 docs/source/_autosummary/datacommons.core.rst delete mode 100644 docs/source/_autosummary/datacommons.places.rst delete mode 100644 docs/source/_autosummary/datacommons.populations.rst delete mode 100644 docs/source/_autosummary/datacommons.query.rst delete mode 100644 docs/source/_autosummary/datacommons.utils.rst delete mode 100644 docs/source/_autosummary/datacommons_core/datacommons.core.get_property_labels.rst delete mode 100644 docs/source/_autosummary/datacommons_core/datacommons.core.get_property_values.rst delete mode 100644 docs/source/_autosummary/datacommons_core/datacommons.core.get_triples.rst delete mode 100644 docs/source/_autosummary/datacommons_places/datacommons.places.get_places_in.rst delete mode 100644 docs/source/_autosummary/datacommons_populations/datacommons.populations.get_observations.rst delete mode 100644 docs/source/_autosummary/datacommons_populations/datacommons.populations.get_place_obs.rst delete mode 100644 docs/source/_autosummary/datacommons_populations/datacommons.populations.get_pop_obs.rst delete mode 100644 docs/source/_autosummary/datacommons_populations/datacommons.populations.get_populations.rst delete mode 100644 docs/source/_autosummary/datacommons_query/datacommons.query.query.rst delete mode 100644 docs/source/_autosummary/datacommons_utils/datacommons.utils.clean_frame.rst delete mode 100644 docs/source/_autosummary/datacommons_utils/datacommons.utils.flatten_frame.rst delete mode 100644 docs/source/_autosummary/datacommons_utils/datacommons.utils.set_api_key.rst delete mode 100644 docs/source/_static/theme_overrides.css delete mode 100644 docs/source/_templates/layout.html delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/data_model.rst delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/modules.rst delete mode 100644 docs/source/started.rst delete mode 100644 docs/source/tutorials.rst diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf1..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index b306f838..00000000 --- a/docs/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# Instructions to Regenerate the Documentation - -Documentation for the Data Commons Python Client API is generated using Sphinx -and hosted on readthedocs.org. - -## Generating Documentation Locally - -To generate documentation locally, - -1. Autogenerate the API documentation using `sphinx-build` by running the - following command in the root directory of this repository: - - ``` - sphinx-build -a docs/source docs/build - ``` - - This generates documentation as `.rst` files from the Python docstrings of - externally facing functions, classes and method in the API while ignoring - test and example files. - -2. Navigate to the `docs/` directory and execute `make html`. This will format - the `.rst` files into `.html`files. - -3. Open `docs/build/html/index.html` to access documentation. - -Local documentation is not meant to be committe! Readthedocs will automatically -build the documentation on a push to the Github repository. - -## Additional Details About Documenting Data Commons - -- We use the `Sphix.ext.napoleon` extension to parse Google style docstrings. diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 6247f7e2..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/_autosummary/datacommons.core.rst b/docs/source/_autosummary/datacommons.core.rst deleted file mode 100644 index a15bcf05..00000000 --- a/docs/source/_autosummary/datacommons.core.rst +++ /dev/null @@ -1,13 +0,0 @@ -datacommons.core -================ - -.. automodule:: datacommons.core - - .. rubric:: Functions - - .. autosummary:: - :toctree: datacommons_core - - get_property_labels - get_property_values - get_triples diff --git a/docs/source/_autosummary/datacommons.places.rst b/docs/source/_autosummary/datacommons.places.rst deleted file mode 100644 index 8152b164..00000000 --- a/docs/source/_autosummary/datacommons.places.rst +++ /dev/null @@ -1,11 +0,0 @@ -datacommons.places -================== - -.. automodule:: datacommons.places - - .. rubric:: Functions - - .. autosummary:: - :toctree: datacommons_places - - get_places_in \ No newline at end of file diff --git a/docs/source/_autosummary/datacommons.populations.rst b/docs/source/_autosummary/datacommons.populations.rst deleted file mode 100644 index 97774221..00000000 --- a/docs/source/_autosummary/datacommons.populations.rst +++ /dev/null @@ -1,14 +0,0 @@ -datacommons.populations -======================= - -.. automodule:: datacommons.populations - - .. rubric:: Functions - - .. autosummary:: - :toctree: datacommons_populations - - get_observations - get_populations - get_pop_obs - get_place_obs diff --git a/docs/source/_autosummary/datacommons.query.rst b/docs/source/_autosummary/datacommons.query.rst deleted file mode 100644 index 58478d98..00000000 --- a/docs/source/_autosummary/datacommons.query.rst +++ /dev/null @@ -1,11 +0,0 @@ -datacommons.query -================= - -.. automodule:: datacommons.query - - .. rubric:: Functions - - .. autosummary:: - :toctree: datacommons_query - - query diff --git a/docs/source/_autosummary/datacommons.utils.rst b/docs/source/_autosummary/datacommons.utils.rst deleted file mode 100644 index 3595439b..00000000 --- a/docs/source/_autosummary/datacommons.utils.rst +++ /dev/null @@ -1,13 +0,0 @@ -datacommons.utils -================= - -.. automodule:: datacommons.utils - - .. rubric:: Functions - - .. autosummary:: - :toctree: datacommons_utils - - set_api_key - clean_frame - flatten_frame diff --git a/docs/source/_autosummary/datacommons_core/datacommons.core.get_property_labels.rst b/docs/source/_autosummary/datacommons_core/datacommons.core.get_property_labels.rst deleted file mode 100644 index 7f45b577..00000000 --- a/docs/source/_autosummary/datacommons_core/datacommons.core.get_property_labels.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.core.get\_property\_labels -====================================== - -.. currentmodule:: datacommons.core - -.. autofunction:: get_property_labels \ No newline at end of file diff --git a/docs/source/_autosummary/datacommons_core/datacommons.core.get_property_values.rst b/docs/source/_autosummary/datacommons_core/datacommons.core.get_property_values.rst deleted file mode 100644 index 1e473199..00000000 --- a/docs/source/_autosummary/datacommons_core/datacommons.core.get_property_values.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.core.get\_property\_values -====================================== - -.. currentmodule:: datacommons.core - -.. autofunction:: get_property_values \ No newline at end of file diff --git a/docs/source/_autosummary/datacommons_core/datacommons.core.get_triples.rst b/docs/source/_autosummary/datacommons_core/datacommons.core.get_triples.rst deleted file mode 100644 index eca9c948..00000000 --- a/docs/source/_autosummary/datacommons_core/datacommons.core.get_triples.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.core.get\_triples -============================= - -.. currentmodule:: datacommons.core - -.. autofunction:: get_triples \ No newline at end of file diff --git a/docs/source/_autosummary/datacommons_places/datacommons.places.get_places_in.rst b/docs/source/_autosummary/datacommons_places/datacommons.places.get_places_in.rst deleted file mode 100644 index 2f249976..00000000 --- a/docs/source/_autosummary/datacommons_places/datacommons.places.get_places_in.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.places.get\_places\_in -================================== - -.. currentmodule:: datacommons.places - -.. autofunction:: get_places_in \ No newline at end of file diff --git a/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_observations.rst b/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_observations.rst deleted file mode 100644 index 597e6275..00000000 --- a/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_observations.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.populations.get\_observations -========================================= - -.. currentmodule:: datacommons.populations - -.. autofunction:: get_observations \ No newline at end of file diff --git a/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_place_obs.rst b/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_place_obs.rst deleted file mode 100644 index 166a7fe2..00000000 --- a/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_place_obs.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.populations.get\_place\_obs -======================================== - -.. currentmodule:: datacommons.populations - -.. autofunction:: get_place_obs diff --git a/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_pop_obs.rst b/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_pop_obs.rst deleted file mode 100644 index dd018989..00000000 --- a/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_pop_obs.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.populations.get\_pop\_obs -======================================== - -.. currentmodule:: datacommons.populations - -.. autofunction:: get_pop_obs diff --git a/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_populations.rst b/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_populations.rst deleted file mode 100644 index 0b3f73ae..00000000 --- a/docs/source/_autosummary/datacommons_populations/datacommons.populations.get_populations.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.populations.get\_populations -======================================== - -.. currentmodule:: datacommons.populations - -.. autofunction:: get_populations \ No newline at end of file diff --git a/docs/source/_autosummary/datacommons_query/datacommons.query.query.rst b/docs/source/_autosummary/datacommons_query/datacommons.query.query.rst deleted file mode 100644 index 5b48b22e..00000000 --- a/docs/source/_autosummary/datacommons_query/datacommons.query.query.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.query.query -========================================= - -.. currentmodule:: datacommons.query - -.. autofunction:: query diff --git a/docs/source/_autosummary/datacommons_utils/datacommons.utils.clean_frame.rst b/docs/source/_autosummary/datacommons_utils/datacommons.utils.clean_frame.rst deleted file mode 100644 index 4e0ad6e0..00000000 --- a/docs/source/_autosummary/datacommons_utils/datacommons.utils.clean_frame.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.utils.clean\_frame -============================== - -.. currentmodule:: datacommons.utils - -.. autofunction:: clean_frame \ No newline at end of file diff --git a/docs/source/_autosummary/datacommons_utils/datacommons.utils.flatten_frame.rst b/docs/source/_autosummary/datacommons_utils/datacommons.utils.flatten_frame.rst deleted file mode 100644 index c62fe162..00000000 --- a/docs/source/_autosummary/datacommons_utils/datacommons.utils.flatten_frame.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.utils.flatten\_frame -================================ - -.. currentmodule:: datacommons.utils - -.. autofunction:: flatten_frame \ No newline at end of file diff --git a/docs/source/_autosummary/datacommons_utils/datacommons.utils.set_api_key.rst b/docs/source/_autosummary/datacommons_utils/datacommons.utils.set_api_key.rst deleted file mode 100644 index 3b959efb..00000000 --- a/docs/source/_autosummary/datacommons_utils/datacommons.utils.set_api_key.rst +++ /dev/null @@ -1,6 +0,0 @@ -datacommons.utils.set\_api\_key -=============================== - -.. currentmodule:: datacommons.utils - -.. autofunction:: set_api_key \ No newline at end of file diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css deleted file mode 100644 index 7c1a5202..00000000 --- a/docs/source/_static/theme_overrides.css +++ /dev/null @@ -1,10 +0,0 @@ -/* override table width restrictions */ -.wy-table-responsive table td, .wy-table-responsive table th { - white-space: normal; -} - -.wy-table-responsive { - margin-bottom: 24px; - max-width: 100%; - overflow: visible; -} diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html deleted file mode 100644 index 3e44f4a3..00000000 --- a/docs/source/_templates/layout.html +++ /dev/null @@ -1,4 +0,0 @@ -{% extends "!layout.html" %} -{% block extrahead %} - -{% endblock %} diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index e3d63f1e..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,75 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. - -import os -import sys -sys.path.insert(0, os.path.abspath('../../')) - - -# -- Project information ----------------------------------------------------- - -project = 'Data Commons' -copyright = '2019, Google Inc.' -author = 'datacommons.org' - -# The full version, including alpha/beta/rc tags -release = '1.0.0' - - -# -- General configuration --------------------------------------------------- - -# The master toctree document. -master_doc = 'index' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.napoleon' -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -html_static_path = ['_static'] - -html_context = { - 'css_files': [ - '_static/theme_overrides.css', # overrides for wide tables in RTD theme - ], - } - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['datacommons.examples.rst', 'datacommons.test.rst'] - -# Autosummary configs -autosummary_generate = True - -# Sphinx napoleon configs -napoleon_numpy_docstring = False -napoleon_use_rtype = False - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'sphinx_rtd_theme' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] diff --git a/docs/source/data_model.rst b/docs/source/data_model.rst deleted file mode 100644 index f1f6720a..00000000 --- a/docs/source/data_model.rst +++ /dev/null @@ -1,144 +0,0 @@ -Getting Started with the Data Model -=================================== - -In this tutorial, we will introduce how Data Commons stores data in its open -knowledge graph. - -Important Terms ---------------- - -The following terms are defined in this tutorial. - -+-----------------+-----------------------------------------------------------+ -| Term | Description | -+=================+===========================================================+ -| Knowledge Graph | The graph structure storing all data in Data Commons. | -+-----------------+-----------------------------------------------------------+ -| Node | The representation of an entity in the knowledge graph. | -+-----------------+-----------------------------------------------------------+ -| DCID | The unique identifier assigned to each node in the Data | -| | Commons knowledge graph. Short for Data Commons | -| | Identifier. | -+-----------------+-----------------------------------------------------------+ -| Type | The class describing a node. For example, the node for | -| | "California" has type "State". | -+-----------------+-----------------------------------------------------------+ -| Property | The relation that associates two nodes together. | -+-----------------+-----------------------------------------------------------+ -| Property Label | Another name for *property*. | -+-----------------+-----------------------------------------------------------+ -| Property Value | The set of nodes adjacent to a given node along edges of | -| | a given *property*. | -+-----------------+-----------------------------------------------------------+ -| Triple | A compact representation of a statement in the Data | -| | Commons knowledge graph of the form | -| | | -| | (subject, property, object) | -| | | -+-----------------+-----------------------------------------------------------+ - -Overview of the Graph ---------------------- - -Data Commons organizes its data as an open access *knowledge graph*. It contains -statements about real world objects such as - -- `"Alameda County" `_ - is contained in the State of - `"California" `_ -- The latitude of - `"Berkeley" `_, CA - is 37.8703 -- The - `population of all persons in Maryland `_ - has a total count of 5,996,080. - -`Entities `_ such as "Alameda County", -"California", and "Berkeley" are represented as **nodes** in the Data Commons -knowledge graph. There are two important details about a node - -1. Every node is uniquely identified by a **dcid** which is short for Data - Commons Identifier. The dcid identifying "California" is :code:`geoId/06` -2. Every node has a **class** that broadly describes the category of entities - that it is an instance of. For example, "California" has type - `State `_. - -Relations between entities are represented as a directed edge between two nodes -in the graph. These relations are called **properties** or **property labels**. -A portion of the Data Commons graph capturing the statement - - "Alameda County is contained in the California" - -can thus be visualized as the following: - -.. image:: https://storage.googleapis.com/notebook-resources/image-1.png - :alt: A view of the statement "Alameda County is contained in California" - :align: center - -Here "Alameda County" and "California" are nodes while -`"containedInPlace" `_ -is a property denoting that the node adjacent to the tail of the edge is -contained in the node adjacent to the head. - -Property Values -+++++++++++++++ - -When accessing nodes in the graph, it is often useful to describe a set of nodes -adjacent to a given node. One may wish to query for all cities that are -contained in a certain county, ask for all schools within a school district, -etc. Given a node and a property, we denote the **property value** as the set -of all nodes that are adjacent to the given node along an edge labeled by the -given property. - -For example, the following are a few property values of "Alameda County" -along the property "containedInPlace". - -- `California `_ -- `Berkeley `_ -- `Oakland `_ -- `Emeryville `_ - -The graph around Alameda County looks like the following. - -.. image:: https://storage.googleapis.com/notebook-resources/readthedocs-image-2.png - :alt: A view of the graph around Alameda County - :align: center - -An important thing to note is that direction matters! Berkeley is certainly -contained in Alameda County, but California is *not* contained in Alameda -County. Alameda County is contained in California, but it is *not* contained -in Berkeley! - -When asking for property values one may thus wish to distinguish by the -*orientation* or direction of the edge. The property values of "Alameda County" -along *outgoing* edges labeled by "containedInPlace" includes California while -property values along *incoming* edges include Berkeley, Oakland, and -Emeryville. - -Triples -+++++++ - -Relations in the graph can be compactly described in the format of a **triple**. -Triples are 3-tuples that take the form `(subject, property, object)`. - -- The *subject* and *object* are two nodes in the Data Commons graph. -- The *property* is the property labeling the edge oriented from subject to - object. - -The statement "Alameda County is contained in the California" can be represented -as a triple of the following form - - ("Alameda County", "containedInPlace", "California") - -Indeed, one could represent the entire Data Commons graph as a collection of -triples. - -More Information ----------------- - -Data Commons leverages the `Schema.org `_ vocabulary to -provide a common set of types and properties. The Data Model used by Data -Commons also closely resembles the Schema.org data model. One may refer to -documentation on the -`Schema.org data model `_ -to learn more. diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 8d06f60f..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. Data Commons Python Client API documentation master file, created by - sphinx-quickstart on Fri Aug 2 15:29:27 2019. - -Data Commons Python Client API -============================== - -.. toctree:: - :maxdepth: 5 - :hidden: - - Getting Started - Tutorials - Modules - License - -Feedback Request ----------------- - -Thank you for using this experimental version of the Python Client API. Please -consider leaving us some feedback so that we can make this library more easy -to use and understand! - -- Send an issue request to the - `Data Commons Issues Page `_. - When creating the issue, choose the template labeled - "Python API v1.0.0 Feedback" - -**DISCLAIMER** This is an experimental version of the Python Client API. The -semantics and availability of this library is subject to change without -prior notice! - -Getting Started ---------------- - -To get started using the Data Commons Python Client API, install the package -from `pip`. - -.. code-block:: bash - - $ pip install -U git+https://github.com/google/datacommons.git@stable-1.x - -Once the package is installed, you can import the :code:`datacommons` package in -Python. - -.. code-block:: python - - import datacommons as dc - -You will additionally need to *provision an API key* to access the Data Commons -graph. See `Getting Started `_ to learn more! - -Overview --------- - -`Data Commons `_ is an open knowledge graph that -connects data from different sources (US Census, NOAA, Bureau of Labor -Statistics, and more) under a single unified representation. It contains -statements about real world entities like - -- Santa Clara County is contained in the State of California -- The latitude of Berkeley, CA is 37.8703 -- The population of all persons in Maryland has a total count of 5,996,080. - -It links references to the same entities (such as cities, counties, -organizations, etc.) across different datasets to nodes in the graph, so that -users can access data about a particular entity aggregated from different -sources. - -The **Data Commons Python Client API** is a Python library that allows -developers to programmatically access nodes in the Data Commons graph. This -package allows users to explore the structure of the graph, integrate statistics -in the Data Commons graph into data analysis workflows and much more. - -Further Resources ------------------ - -To learn more about Data Commons and get involved, please visit the following -resources. - -- `Our homepage `_ -- `Our GitHub Page `_ -- `Our Issues Page `_ -- `More packages for accessing Data Commons `_ diff --git a/docs/source/modules.rst b/docs/source/modules.rst deleted file mode 100644 index 132e6333..00000000 --- a/docs/source/modules.rst +++ /dev/null @@ -1,11 +0,0 @@ -datacommons -=========== - -.. autosummary:: - :toctree: _autosummary - - datacommons.core - datacommons.places - datacommons.populations - datacommons.query - datacommons.utils diff --git a/docs/source/started.rst b/docs/source/started.rst deleted file mode 100644 index a12ce17f..00000000 --- a/docs/source/started.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. _getting_started: - -Getting Started -=============== - -To get started using the Python Client API requires four steps. - -- Install the API using :code:`pip` -- Create an API key on `Google Cloud Platform `_ (GCP) -- Enable the *Data Commons API* on GCP. Note that this is separate from the - *Python Client API*. -- Provide the API key to the Python Client API and begin developing. - -Installing the Python Client API --------------------------------- - -First, install the :code:`datacommons` package through :code:`pip`. - -.. code-block:: bash - - $ pip install -U git+https://github.com/google/datacommons.git@stable-1.x - -For more information about installing :code:`pip` and setting up other parts of -your Python development environment, please refer to the -`Python Development Environment Setup Guide `_ -for Google Cloud Platform. - -Creating an API Key -------------------- - -Using the Data Commons Python API requires you to provision an API key on GCP. -Follow these steps to create your own key. - -1. Start by creating a `GCP Project`_ and `enabling billing`_ for that project. -2. After creating your project, you can navigate to the GCP Console to create - an API key. - - - Begin by navigating to **APIs & Services > Credentials** in the side - bar or by clicking on - `this link `_ - - Click **Create Credentials** then select **API Key** - - Once you do this, you'll be presented a key that you can copy to your - clipboard. - -.. _`GCP Project`: https://console.developers.google.com/projectcreate -.. _`enabling billing`: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project - -Enable the Data Commons API ---------------------------- - -Additionally, you will need to enable the *Data Commons API* on GCP which is -separate from the *Python Client API*. This service enables the Python Client -API to call our REST service and access data in our knowledge graph. To enable -the API, do the following. - -1. Navigate to the datacommons-users `Google Group`_. Please join the group with the same Google account used to create the GCP project. -2. Navigate to the `Data Commons API`_ in the Google APIs Console. -3. Click the :code:`Enable` button and wait for the process to complete. - -.. _`Google Group`: https://groups.google.com/forum/#!forum/datacommons-users -.. _`Data Commons API`: https://console.developers.google.com/apis/api/api.datacommons.org/overview?pli=1 - -Using the Python Client API ---------------------------- - -With the API key created and Data Commons API activated, we can now get started -using the Data Commons Python Client API. There are two ways to provide your key -to the Python Client API package. - -1. You can set the API key by calling :py:func:`datacommons.utils.set_api_key`. - Start by importing :code:`datacommons`, then set the API key like so. - - .. code-block:: python - - import datacommons as dc - - dc.set_api_key('YOUR-API-KEY') - - This will create an environment variable in your Python runtime called - :code:`DC_API_KEY` holding your key. Your key will then be used whenever - the package sends a request to the Data Commons graph. - -2. You can export an environment variable in your shell like so. - - .. code-block:: bash - - export DC_API_KEY='YOUR-API-KEY' - - After you've exported the variable, you can start using the Data Commons - package! - - .. code-block:: python - - import datacommons as dc - - This route is particularly useful if you are building applications that - depend on this API, and are deploying them to hosting services. - -You are now ready to go! From here you can view our tutorials on how to use the -API to perform certain tasks, or see a full list of functions, classes and -methods available for use by navigating to `modules `_ diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst deleted file mode 100644 index db9a9070..00000000 --- a/docs/source/tutorials.rst +++ /dev/null @@ -1,31 +0,0 @@ -Tutorials -========= - -.. toctree:: - :maxdepth: 5 - :hidden: - - The Data Commons Data Model - Analyzing Employment in California Counties - -We have a number of tutorials that will help acclimate you to how data is -represented in the Data Commons graph and how to use the Python Client API -to access that data. - -+-------------------------------------------------+------------------------------------------------------------------------+ -| Tutorial | Description | -+=================================================+========================================================================+ -| `The Data Commons Data Model`_ | This tutorial introduces the Data Commons data model and defines | -| | terms that are used throughout the API such as “dcid”, | -| | “triples”, “property label”, “property value” and more. | -+-------------------------------------------------+------------------------------------------------------------------------+ -| `Analyzing Employment in California Counties`_ | This Colab notebook demonstrates how to use Data Commons to access | -| | employment statistics provided by the `Bureau of Labor Statistics`_ | -| | and store them in a :code:`pandas.DataFrame`. The end goal of this | -| | tutorial will be to generate a bar chart visualizing the total | -| | number of employed persons across all California counties. | -+-------------------------------------------------+------------------------------------------------------------------------+ - -.. _`The Data Commons Data Model`: data_model.html -.. _`Analyzing Employment in California Counties`: https://colab.research.google.com/drive/1ZNXTHu3J0W3vo9Mg3kNUpk0hnD6Ce1u6 -.. _`Bureau of Labor Statistics`: https://www.bls.gov/ From defb7d15775bbd5ad250d9ff5a466fd06b5b6eff Mon Sep 17 00:00:00 2001 From: Bo Xu Date: Fri, 3 Apr 2020 17:42:35 -0700 Subject: [PATCH 3/3] Add back tutorial page --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 68548358..0cee6b69 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,10 @@ GCP. Once you have the API key, simply add the following line to your code. For more detail on getting started with the API, please visit [Getting Started](http://docs.datacommons.org/api/). +After you're ready to use the API, you can refer to `datacommons/examples` for +examples on how to use this package to perform various tasks. More tutorials and +documentation can be found at [tutorials](https://datacommons.org/colab)! + ## About Data Commons [Data Commons](https://datacommons.org/) is an Open Knowledge Graph that