diff --git a/README.md b/README.md index 417e5be..bffea0e 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,10 @@ This repo contains Python source and example files for the Tableau Document API. We're just getting started and have plans to expand what you find here. Help us by submitting feedback, issues, and pull requests! +For more information, see the documentation: + + + Document API --------------- The Document API provides a supported way to programmatically make updates to Tableau workbook and data source files. If you've been making changes to these file types by directly updating the XML--that is, by XML hacking--this SDK is for you :) @@ -26,84 +30,3 @@ Features include: - Get all fields in use by certain sheets in a workbook We don't yet support creating files from scratch, adding extracts into workbooks or data sources, or updating field information - - -###Getting Started -To use this SDK, you must have Python installed. You can use either 2.7.X or 3.3 and later. - -#### Installing the latest stable version (preferred) - -```text -pip install tableaudocumentapi -``` - -#### Installing From Source - -Download the `.zip` file that contains the SDK. Unzip the file and then run the following command: - -```text -pip install -e -``` - -#### Installing the Development Version from Git - -*Only do this if you know you want the development version, no guarantee that we won't break APIs during development* - -```text -pip install git+https://github.com/tableau/document-api-python.git@development -``` - -If you go this route, but want to switch back to the non-development version, you need to run the following command before installing the stable version: - -```text -pip uninstall tableaudocumentapi -``` - -###Basics -The following example shows the basic syntax for using the Document API to update a workbook: - -```python -from tableaudocumentapi import Workbook - -sourceWB = Workbook('WorkbookToUpdate.twb') - -sourceWB.datasources[0].connections[0].server = "MY-NEW-SERVER" -sourceWB.datasources[0].connections[0].dbname = "NEW-DATABASE" -sourceWB.datasources[0].connections[0].username = "benl" - -sourceWB.save() -``` - -With Data Integration in Tableau 10, a data source can have multiple connections. To access the connections simply index them like you would datasources. - -```python -from tableaudocumentapi import Workbook - -sourceWB = Workbook('WorkbookToUpdate.twb') - -sourceWB.datasources[0].connections[0].server = "MY-NEW-SERVER" -sourceWB.datasources[0].connections[0].dbname = "NEW-DATABASE" -sourceWB.datasources[0].connections[0].username = "benl" - -sourceWB.datasources[0].connections[1].server = "MY-NEW-SERVER" -sourceWB.datasources[0].connections[1].dbname = "NEW-DATABASE" -sourceWB.datasources[0].connections[1].username = "benl" - - -sourceWB.save() -``` - - -**Notes** - -- Import the `Workbook` object from the `tableaudocumentapi` module. -- To open a workbook, instantiate a `Workbook` object and pass the file name as the first argument. -- The `Workbook` object exposes a list of `datasources` in the workbook -- Each data source object has a `connection` object that supports a `server`, `dbname`, and `username` property. -- Save changes to the workbook by calling the `save` or `save_as` method. - - - -###[Examples](samples) - -The downloadable package contains several example scripts that show more detailed usage of the Document API. diff --git a/docs/_includes/analytics.html b/docs/_includes/analytics.html new file mode 100644 index 0000000..0cdbad2 --- /dev/null +++ b/docs/_includes/analytics.html @@ -0,0 +1,7 @@ + + + diff --git a/docs/_includes/head.html b/docs/_includes/head.html index 0101425..40578e9 100644 --- a/docs/_includes/head.html +++ b/docs/_includes/head.html @@ -14,3 +14,5 @@ + +{% if jekyll.environment == "production" %}{% include analytics.html %}{% endif %} diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md index 1d45c67..7c08244 100644 --- a/docs/docs/contributing.md +++ b/docs/docs/contributing.md @@ -51,8 +51,7 @@ anyone can add to an issue: ## Fixes, Implementations, and Documentation -For all other things, please submit a PR that includes the fix, documentation, or new code that you are trying to contribute. More information on -creating a PR can be found in the [github documentation](https://help.github.com/articles/creating-a-pull-request/) +For all other things, please submit a PR that includes the fix, documentation, or new code that you are trying to contribute. More information on submitting a PR can be found in the [developer guide](dev-guide.md) If the feature is complex or has multiple solutions that could be equally appropriate approaches, it would be helpful to file an issue to discuss the design trade-offs of each solution before implementing, to allow us to collectively arrive at the best solution, which most likely exists in the middle diff --git a/docs/docs/dev-guide.md b/docs/docs/dev-guide.md index a77013f..c6b1e59 100644 --- a/docs/docs/dev-guide.md +++ b/docs/docs/dev-guide.md @@ -3,7 +3,6 @@ title: Developer Guide layout: docs --- -<<<<<<< 6ee666bf06d5ab59931100b3955779c35693e33f ## Submitting your first patch 1. Make sure you have [signed the CLA](http://tableau.github.io/#contributor-license-agreement-cla) @@ -18,13 +17,19 @@ layout: docs git clone http://github.com//document-api-python ``` +1. Check out the development branch + + ```shell + git checkout development + ``` + 1. Run the tests to make sure everything is peachy: ```shell python setup.py test ``` -1. Set up the feature, fix, or documentation branch. +1. Set up the feature, fix, or documentation branch. It is recommended to use the format issue#-type-description (e.g. 13-fix-connection-bug) like so: @@ -53,7 +58,7 @@ layout: docs Our documentation is written in markdown and built with Jekyll on Github Pages. All of the documentation source files can be found in `docs/docs`. When adding a new feature or improving existing functionality we may ask that you update the documentation along with your code. - + If you are just making a PR for documentation updates (adding new docs, fixing typos, improving wording) the easiest method is to use the built in `Edit this file` in the Github UI 1. Submit to your fork.