Merge pull request #310 from pcattori/ci-docs

Treat sphinx-build warnings as errors in CI

.travis.yml

@@ -10,6 +10,7 @@ script:
 - poetry run black --check .
 - poetry run flake8 .
 - poetry run pytest tests
+- cd docs && poetry run sphinx-build -b html . _build -W
 before_deploy:
 - poetry build
 - poetry config http-basic.pypi $PYPI_USERNAME $PYPI_PASSWORD

docs/conf.py

@@ -54,9 +54,11 @@
     "sphinx_autodoc_typehints",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    "sphinx.ext.autosectionlabel",
 ]
 autodoc_default_flags = ["inherited-members", "members"]
 autodoc_member_order = "bysource"
+autosectionlabel_prefix_document = True
 intersphinx_mapping = {
     "https://docs.python.org/": None,
     "requests": ("https://requests.kennethreitz.org/en/master/", None),

docs/developer-interface.rst

@@ -13,8 +13,8 @@ Client
 .. autoclass:: tamr_unify_client.Client
   :members:
 
-Attribute
----------
+Attributes
+----------
 
 Attribute
 ^^^^^^^^^
@@ -60,8 +60,8 @@ Categorization Project
 .. autoclass:: tamr_unify_client.categorization.project.CategorizationProject
   :members:
 
-Category
-^^^^^^^^
+Categories
+^^^^^^^^^^
 
 Category
 """"""""
@@ -87,8 +87,8 @@ Taxonomy
 .. autoclass:: tamr_unify_client.categorization.taxonomy.Taxonomy
   :members:
 
-Dataset
--------
+Datasets
+--------
 
 Dataset
 ^^^^^^^
@@ -167,8 +167,8 @@ Mastering Project
 .. autoclass:: tamr_unify_client.mastering.project.MasteringProject
   :members:
 
-Published Cluster
-^^^^^^^^^^^^^^^^^
+Published Clusters
+^^^^^^^^^^^^^^^^^^
 
 Metric
 """"""
@@ -212,11 +212,11 @@ Operation
   :members:
 
 
-Project
--------
+Projects
+--------
 
-Attribute Configuration
-^^^^^^^^^^^^^^^^^^^^^^^
+Attribute Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Attribute Configuration
 """""""""""""""""""""""
@@ -237,8 +237,8 @@ Attribute Configuration Collection
   :members:
 
 
-Attribute Mapping
-^^^^^^^^^^^^^^^^^
+Attribute Mappings
+^^^^^^^^^^^^^^^^^^
 
 Attribute Mapping
 """""""""""""""""

docs/user-guide/advanced-usage.md

@@ -60,7 +60,7 @@ tamr.log_entry = log_entry
 ```
 
 
-## Custom HTTP requests and Unversioned API Access
+## Raw HTTP requests and Unversioned API Access
 
 We encourage you to use the high-level, object-oriented interface offered by the Python Client. If you aren't sure whether you need to send low-level HTTP requests, you probably don't.
 

docs/user-guide/faq.md

@@ -0,0 +1,24 @@
+# FAQ
+
+## What version of the Python Client should I use?
+
+The Python Client just cares about features, and will try everything it knows to implement those features correctly, independent of the API version.
+
+If you are starting a new project or your existing project does not yet use the Python Client, we encourage you to use the **latest stable version** of the Python Client.
+
+Otherwise, check the [Change Log](https://github.com/Datatamer/tamr-client/blob/master/CHANGELOG.md) to see:
+
+* what new features and bug fixes are available in newer versions
+* which breaking changes (if any) will require changes in your code to get those new features and bug fixes
+
+Note: You do not need to reason about the Tamr API version nor the the Tamr app/server version.
+
+## How do I call custom endpoints, e.g. endpoints outside the Tamr API?
+
+To call a custom endpoint *within* the Tamr API, use the `client.request()` method, and provide an endpoint described by a path relative to `base_path`.
+
+For example, if `base_path` is `/api/versioned/v1/` (the default), and you want to get `/api/versioned/v1/projects/1`, you only need to provide `projects/1` (the relative ID provided by the project) as the endpoint, and the Client will resolve that into `/api/versioned/v1/projects/1`.
+
+There are various APIs outside the `/api/versioned/v1/` prefix that are often useful or necessary to call - e.g. `/api/service/health`, or other un-versioned / unsupported APIs. To call a custom endpoint *outside* the Tamr API, use the `client.request()` method, and provide an endpoint described by an *absolute* path (a path starting with `/`). For example, to get `/api/service/health` (no matter what `base_path` is), call `client.request()` with `/api/service/health` as the endpoint. The Client will ignore `base_path` and send the request directly against the absolute path provided.
+
+For additional detail, see [Raw HTTP requests and Unversioned API Access](<user-guide/advanced-usage:Raw HTTP requests and Unversioned API Access>)