8000 Crack at a mkdocs build skeleton · tableau/document-api-python@601b05c · GitHub
[go: up one dir, main page]
Skip to content

Commit 601b05c

Browse files
t8y8t8y8
committed
Crack at a mkdocs build skeleton
1 parent cb0de80 commit 601b05c

File tree

7 files changed

+266
-0
lines changed

7 files changed

+266
-0
lines changed

‎docs/api-ref.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Workbooks
2+
```python
3+
class Workbook(filename):
4+
```
5+
6+
The Workbook class represents a tableau workbook. It may be either a TWB or TWBX, and the library will handle packaging and unpackaging automatically.
7+
8+
**Params:**
9+
`filename` takes a string representing the path to the workbook file.
10+
11+
**Raises:**
12+
`TableauVersionNotSupportedException` if the workbook is not a supported version
13+
`TableauInvalidFileException` if the file is not a valid tableau workbook file
14+
15+
**Methods:**
16+
`Workbook.save(self):`
17+
Saves any changes to the workbook to the existing file
18+
19+
`Workbook.save_as(self, new_filename):`
20+
Saves any changes to the workbook to a new file specified by the `new_file` parameter
21+
22+
**Properities:**
23+
`self.worksheets:` Returns a list of worksheets found in the workbook
24+
`self.datasources:` Returns a list of Datasource objects found in the workbook
25+
`self.filename:` Returns the filename of the workbook
26+
27+
#Datasources
28+
```python
29+
class Datasource(dsxml, filename=None)
30+
```
31+
32+
# Connections
33+
```python
34+
class Connection(connxml)
35+
```
36+
37+
# Fields
38+
```python
39+
class Workbook(column_xml=None, metadata_xml=None)
40+
```

‎docs/contributing.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Contributing
2+
3+
We welcome contributions to this project!
4+
5+
There are many ways to contribute! We welcome all contributions including:
6+
7+
* File an Issue
8+
* Request a Feature
9+
* Implement a Requested Feature
10+
* Fix an Issue/Bug
11+
* Add/Fix documentation
12+
13+
Contributions must follow the guidelines outlined on the [Tableau Organization](http://tableau.github.io/) page, though filing an issue or requesting
14+
a feature do not require the CLA.
15+
16+
## Issues and Feature Requests
17+
18+
To submit an issue/bug report, or to request a feature, please submit a [github issue](https://github.com/tableau/document-api-python/issues) to the repo.
19+
20+
If you are submiting a bug report, please provide as much information as you can, including clear and concise repro steps, attaching any necessary
21+
files to assist in the repro. **Be sure to scrub the files of any potentially sensitive information. Issues are public.**
22+
23+
For a feature request, please try to describe the scenario you are trying to accomplish that requires the feature. This will help us understand
24+
the limitations that you are running into, and provide us with a use case to know if we've satisfied your request. Psuedo code that describes how you would like things to work is also very helpful.
25+
26+
## Fixes, Implementations, and Documentation
27+
28+
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
29+
creating a PR can be found in the [github documentation](https://help.github.com/articles/creating-a-pull-request/)
30+
31+
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
32+
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 somewhere.

‎docs/css/extra.css

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
pre code {
2+
white-space: pre;
3+
word-wrap: normal;
4+
display: block;
5+
padding: 12px;
6+
font-size: 14px;
7+
}
8+
9+
code {
10+
white-space: pre-wrap;
11+
word-wrap: break-word;
12+
padding: 2px 5px;
13+
font-size: 16px;
14+
}

‎docs/devguide.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
Developer Guide
2+
---------------
3+
4+
### Making your first patch
5+
6+
0. Make sure you've signed the CLA
7+
1. Clone the repo
8+
9+
```shell
10+
git clone http://github.com/tableau/document-api-python
11+
```
12+
13+
2. Run the tests to make sure everything is peachy
14+
15+
```shell
16+
python setup.py test
17+
```
18+
19+
3. Set up the feature, fix, or documentation branch.
20+
It is recommended to use the format [issue#]-[type]-[description] (e.g. 13-fix-connection-bug)
21+
22+
```shell
23+
git checkout -b 13-feature-new-stuff
24+
```
25+
26+
4. Code and Commit!
27+
Here's a quick checklist for ensuring a good diff:
28+
- The diff touches the minimal amount of files possible while still fufilling the purpose of the diff
29+
- The diff uses Unix line endings
30+
- The diff adheres to our PEP8 style guides. If you've cloned the repo you can run `pycodestyle .`
31+
5. Add Tests
32+
6. Update Documentation
33+
Our documentation is written in markdown and built with [Mkdocs](http://www.mkdocs.org). More information on how to update and build the docs can be found [here](#updating-documentation)
34+
7. Run the tests again and make sure they pass!
35+
8. Submit to your fork
36+
9. Submit a PR
37+
10. Wait for a review, and address any feedback.
38+
39+
### Updating Documentation
40+
41+
### Running Tests

‎docs/index.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
Tableau Document API
2+
----------------------
3+
4+
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!
5+
6+
7+
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 :)
8+
9+
10+
Features include:
11+
12+
- Support for 9.X, and 10.X workbook and data source files
13+
- Including TDSX and TWBX files
14+
- Getting connection information from data sources and workbooks
15+
- Server Name
16+
- Username
17+
- Database Name
18+
- Authentication Type
19+
- Connection Type
20+
- Updating connection information in workbooks and data sources
21+
- Server Name
22+
- Username
23+
- Database Name
24+
- Getting Field information from data sources and workbooks
25+
- Get all fields in a data source
26+
- Get all fields in use by certain sheets in a workbook
27+
28+
We don't yet support creating files from scratch, adding extracts into workbooks or data sources, or updating field information
29+
30+
31+
### Getting Started
32+
To use this SDK, you must have Python installed. You can use either 2.7.X or 3.3 and later.
33+
34+
#### Installing the latest stable version (preferred)
35+
36+
```shell
37+
pip install tableaudocumentapi
38+
```
39+
40+
#### Installing From Source
41+
42+
Download the `.zip` file that contains the SDK. Unzip the file and then run the following command:
43+
44+
```shell
45+
pip install -e <directory containing setup.py>
46+
```
47+
48+
#### Installing the Development Version from Git
49+
50+
*Only do this if you know you want the development version, no guarantee that we won't break APIs during development*
51+
52+
```shell
53+
pip install git+https://github.com/tableau/document-api-python.git@development
54+
```
55+
56+
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:
57+
58+
```shell
59+
pip uninstall tableaudocumentapi
60+
```
61+
62+
###Basics
63+
The following example shows the basic syntax for using the Document API to update a workbook:
64+
65+
```python
66+
from tableaudocumentapi import Workbook
67+
68+
sourceWB = Workbook('WorkbookToUpdate.twb')
69+
70+
sourceWB.datasources[0].connections[0].server = "MY-NEW-SERVER"
71+
sourceWB.datasources[0].connections[0].dbname = "NEW-DATABASE"
72+
sourceWB.datasources[0].connections[0].username = "benl"
73+
74+
sourceWB.save()
75+
```
76+
77+
With Data Integration in Tableau 10, a data source can have multiple connections. To access the connections simply index them like you would datasources.
78+
79+
```python
80+
from tableaudocumentapi import Workbook
81+
82+
sourceWB = Workbook('WorkbookToUpdate.twb')
83+
84+
sourceWB.datasources[0].connections[0].server = "MY-NEW-SERVER"
85+
sourceWB.datasources[0].connections[0].dbname = "NEW-DATABASE"
86+
sourceWB.datasources[0].connections[0].username = "benl"
87+
88+
sourceWB.datasources[0].connections[1].server = "MY-NEW-SERVER"
89+
sourceWB.datasources[0].connections[1].dbname = "NEW-DATABASE"
90+
sourceWB.datasources[0].connections[1].username = "benl"
91+
92+
93+
sourceWB.save()
94+
```
95+
96+
97+
**Notes**
98+
99+
- Import the `Workbook` object from the `tableaudocumentapi` module.
100+
- To open a workbook, instantiate a `Workbook` object and pass the file name as the first argument.
101+
- The `Workbook` object exposes a list of `datasources` in the workbook
102+
- Each data source object has a `connection` object that supports a `server`, `dbname`, and `username` property.
103+
- Save changes to the workbook by calling the `save` or `save_as` method.
104+
105+
!!! tip "Introduced In v 2.4"
106+
This call was added in version Tableau 10.3, XSDv2.5
107+
108+
###[Examples](samples)
109+
110+
The downloadable package contains several example scripts that show more detailed usage of the Document API.

‎docs/user-guide.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Concepts
2+
3+
Imagine a world without kittens. What a world that would be.
4+
This is why I am going to discuss our document object model. You see
5+
it all starts with Workbooks, Datasources, and Connections. There are
6+
also Fields.

‎mkdocs.yml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Site information
2+
site_name: Tableau Document API (Python)
3+
repo_url: https://github.com/tableau/document-api-python/
4+
copyright: © Tableau Software
5+
6+
# Pages and Layout
7+
pages:
8+
- Intro: index.md
9+
- Documentation:
10+
- 'User Guide': user-guide.md
11+
- 'API Ref': api-ref.md
12+
- Contributing:
13+
- contributing.md
14+
- devguide.md
15+
16+
theme: readthedocs
17+
extra_css:
18+
- css/extra.css
19+
20+
# Markdown Stuff
21+
markdown_extensions:
22+
- admonition # Customize for 'Version Added' ?
23+
- pymdownx.extra # To use superfences so code and lists work nicely

0 commit comments

Comments
 (0)
0