|
1 | | -# Contribute to Plotly's [Python Documentation](https://plot.ly/python/) |
2 | | -## Initial Steps: |
3 | | -1. Clone the repo and then check out the master branch: |
4 | | - |
5 | | - ``` |
6 | | - $ git clone git@github.com:plotly/graphing-library-docs.git |
7 | | - $ git fetch origin |
8 | | - $ git checkout master |
9 | | - ``` |
10 | | - |
11 | | -2. Check Ruby version `$ ruby --version`. We recommend using `version 2.3.3` or the same ruby version as gh-pages: https://pages.github.com/versions/. Note [RVM](https://rvm.io/rvm/install) is helpful for installing and managing ruby versions. |
12 | | - |
13 | | -3. Install bundler and a couple dependencies from the gemfile: |
14 | | - |
15 | | - ``` |
16 | | - $ gem install bundler |
17 | | - $ bundle install |
18 | | -
|
19 | | - ``` |
20 | | -<b>IMPORTANT</b> -If not using bundler and the gemfile, [install the same jekyll version that GitHub Pages is using](https://pages.github.com/versions/). |
21 | | - |
22 | | -## Create Python Documentation: |
23 | | -Our python tutorials are written in [ipython notebooks](http://ipython.org/notebook.html) (.ipynb file) |
24 | | -##### In `documentation/_posts/python` |
25 | | -1. Create a folder titled with the chart type or topic you're adding to the documentation (i.e. `table`) |
26 | | -2. `cd` into the folder you created and run `ipython notebook` |
27 | | - - From the <b>New</b> dropdown create a new notebook and title it based on the type of chart you're adding to the documentation. |
28 | | -3. Base your tutorial structure off of one of our existing tutorials (i.e. `documentation/_posts/python/table/table.ipynb`) |
29 | | -4. The first cell should be a markdown cell with the following text: |
30 | | - |
31 | | - ``` |
32 | | - #### New to Plotly? |
33 | | - Plotly's Python library is free and open source! [Get started](https://plot.ly/python/getting-started/) by downloading the client and [reading the primer](https://plot.ly/python/getting-started/). |
34 | | - <br>You can set up Plotly to work in [online](https://plot.ly/python/getting-started/#initialization-for-online-plotting) or [offline](https://plot.ly/python/getting-started/#initialization-for-offline-plotting) mode, or in [jupyter notebooks](https://plot.ly/python/getting-started/#start-plotting-online). |
35 | | - <br>We also have a quick-reference [cheatsheet](https://images.plot.ly/plotly-documentation/images/python_cheat_sheet.pdf) (new!) to help you get started! |
36 | | - ``` |
37 | | -
|
38 | | -5. **IF** you're adding a doc about a new feature, the second and third cells will display a version check. This is to ensure the reader has updated to the necessary version. This is especially applicable to FigureFactory docs. You can refer to the python api [CHANGELOG](https://github.com/plotly/plotly.py/blob/master/CHANGELOG.md) to check the appropriate version #. Example of a version check: |
39 | | - - markdown cell: |
40 | | - ``` |
41 | | - #### Version Check |
42 | | - Plotly's python package is updated frequently. Run `pip install plotly --upgrade` to use the latest version. |
43 | | - ``` |
44 | | -
|
45 | | - - code cell: |
46 | | - ``` |
47 | | - import plotly |
48 | | - plotly.__version__ |
49 | | - ``` |
50 | | -
|
51 | | -6. Best Practices: |
52 | | - - <b>Now we have an awesome navigation bar on the left side of our tutorial pages.</b> The navigation bar displays the headers you add to your notebook so add a header for each example and try to make headers as informative and concise as possible. Furthermore, capitalize all headers (except for `code`). Ex: `#### Basic Line Chart` |
53 | | - - Order examples from basic -> advanced. |
54 | | - - Run examples with user: `PythonPlotBot` |
55 | | - - Keep import order consistent and import plotly packages first, then a space, then additional packages. For example: |
56 | | -
|
57 | | - ``` |
58 | | - import plotly.plotly as py |
59 | | - import plotly.graph_objs as go |
60 | | -
|
61 | | - import pandas as pd |
62 | | - import numpy as np |
63 | | - ``` |
64 | | -
|
65 | | - - Try and write all of the code for a given example in a *single* ipython notebook cell. This makes it easier for users to use the `copy to clipboard` button that appears on the codeblocks and easily/quickly reproduce each example. |
66 | | - - If you're using "real" data, upload the datafile to https://github.com/plotly/datasets then import data rather than pasting a large chunk of data in the tutorial. (Using random data is okay for some examples too :) ) |
67 | | -
|
68 | | -7. The last content cell of your notebook should be a markdown cell with: |
69 | | -
|
70 | | - ``` |
71 | | - #### Reference |
72 | | - See https://plot.ly/python/reference/##heatmap for more information and chart attribute options! |
73 | | - ``` |
74 | | -
|
75 | | - where `https://plot.ly/python/reference/##heatmap` is replaced with the pertinent link(s) to our python [reference |
76 | | - page](https://plot.ly/python/reference/)! |
77 | | -
|
78 | | - and/or provide a help call: |
79 | | - `help(FF.create_table)` (*This applies to documentation on FigureFactory functions) |
80 | | -
|
81 | | -8. Convert your .ipynb to a .html file by adding the following code snippet as the last cell of your notebook. |
82 | | - - Replace `your-tutorial-chart` with the type of chart you're creating in the tutorial.) |
83 | | - - Please be diligent about adding this information completely and in the order as it appears here (this is really helpful if future edits are necessary :D ) |
84 | | -
|
85 | | - ``` |
86 | | - from IPython.display import display, HTML |
87 | | - |
88 | | - display(HTML('<link href="//fonts.googleapis.com/css?family=Open+Sans:600,400,300,200|Inconsolata|Ubuntu+Mono:400,700" rel="stylesheet" type="text/css" />')) |
89 | | - display(HTML('<link rel="stylesheet" type="text/css" href="http://help.plot.ly/documentation/all_static/css/ipython-notebook-custom.css">')) |
90 | | - |
91 | | - ! pip install git+https://github.com/plotly/publisher.git --upgrade |
92 | | - import publisher |
93 | | - publisher.publish( |
94 | | - 'your-tutorial-chart.ipynb', 'python/your-tutorial-chart/', 'Your Tutorial Chart', |
95 | | - 'How to make your-tutorial-chart plots in Python with Plotly.', |
96 | | - title = 'Python Your Tutorial Chart | Plotly', |
97 | | - has_thumbnail='true', thumbnail='thumbnail/your-tutorial-chart.jpg', |
98 | | - language='python', |
99 | | - # page_type='example_index', // note this is only if you want the tutorial to appear on the main page: plot.ly/python |
100 | | - display_as='chart_type', order=2, ipynb='~notebook_demo/1', |
101 | | - uses_plotly_offline=False*) |
102 | | - ``` |
103 | | - - always include a trailing slash in the permalink (i.e. python/your-tutorial-chart/) |
104 | | - - `display_as` sets in which section your tutorial is displayed |
105 | | - - 'basic' = https://plot.ly/python/#basic-charts |
106 | | - - 'statistical' = https://plot.ly/python/#statistical-charts |
107 | | - - 'scientific' = https://plot.ly/python/#scientific-charts |
108 | | - - 'financial' = https://plot.ly/python/#financial-charts |
109 | | - - 'maps' = https://plot.ly/python/#maps |
110 | | - - '3d_charts' = https://plot.ly/python/#3d-charts |
111 | | - - See additional options [HERE](https://github.com/plotly/graphing-library-docs/blob/master/_includes/documentation_eg.html#L1) |
112 | | - - `order` defines the order in which the tutorials appear on plot.ly/python. Please take a look at https://plot.ly/python/ and order your tutorial next to similar chart types. <b>Note</b> `order` can be a float. |
113 | | - - `uses_plotly_offline` is an optional argument, include as `True` if you're creating an offline doc. |
114 | | -
|
115 | | -9. Now we can upload/download jupyter (ipython) notebooks to Plotly!!!! |
116 | | - - There is a button in our side navigation bar of the python docs so users can click the button and see the notebook hosted on plot.ly where they can download it and run it to follow along with the documentation. |
117 | | - - Use the bubble chart doc: https://plot.ly/python/bubble-charts/ as an example. |
118 | | - - Here are step by step instructions of how to enable the `Download THIS Notebook` button: |
119 | | - 1. Copy the notebook from the folder. For example from the [bubble folder](https://github.com/plotly/graphing-library-docs/tree/master/_posts/python/v3/bubble), copy `bubble.ipynb`. |
120 | | - 2. Run `ipython notebook` or `jupyter notebook` and remove the publisher cell from your copy. (The publisher cell is the last cell that we add to our doc notebooks to convert the `.ipynb` to `html`. We do not need to upload this. _Do not remove this cell from the .ipynb in the doc repo_). Save. |
121 | | - 3. Upload the copy to the `notebook_demo` Plotly account. |
122 | | - 4. View the notebook: the link is: https://plot.ly/~notebook_demo/1/new-to-plotly-plotlys-python-library-i/ Grab the username + file id # from the link: `~notebook_demo/1` and add it to the publisher cell in the original .ipynb file in the doc repo. See example publisher cell below. |
123 | | -
|
124 | | -10. Add Thumbnail Images |
125 | | - - Thumbnail images should named `your-tutorial-chart.jpg` and be *EXACTLY* 160px X 160px |
126 | | - - Thumbnail images should be clear and interesting. You do not need to capture the ENTIRE chart, but rather focus on the most interesting part of the chart. |
127 | | - - Use images.plot.ly for adding new images. |
128 | | - - Log-in here: https://661924842005.signin.aws.amazon.com/console |
129 | | - - Username: Plotly_Editors |
130 | | - - From the <b>Amazon Web Services Console</b> select <b>S3 (Scalable Storage in the Cloud)</b> then select <b>plotly-tutorials</b> -> <b>plotly-documentation</b> -> <b>thumbnail</b> |
131 | | - - Now from <b>All Buckets /plotly-tutorials/plotly-documentation/thumbnail</b> select the <b>Actions</b> dropdown and <b>upload</b> your .jpg file |
132 | | -
|
133 | | -##### In the terminal in `documentation` |
134 | | -9. Make a PR |
135 | | -
|
136 | | - - Ready for your changes to be reviewed? Make a pull request against the `master` branch! |
137 | | - Create a feature branch and use `git status` to list changed files. |
138 | | - ``` |
139 | | - git checkout -b your_feature_branch |
140 | | - git status |
141 | | - ``` |
142 | | - - Add, commit, and push the files that you'd like to add to your PR: |
143 | | - ``` |
144 | | - git add file-a |
145 | | - git add file-b |
146 | | - git commit -m 'message about your changes' |
147 | | - git push origin your_feature_branch |
148 | | - ``` |
149 | | - - Visit the [documentation repo](https://github.com/plotly/graphing-library-docs) and open a pull request against the `master` branch. You can then tag **@jdamiba** for a review. |
150 | | -
|
151 | | -10. To proof your work follow these steps: https://github.com/plotly/graphing-library-docs/blob/master/Contributing.md |
152 | | -
|
153 | | -##### At https://plot.ly/python |
154 | | -11. Your changes haven't been deployed yet so they won't be online. That said, <b>PLEASE</b> visit https://plot.ly/python/your-tutorial and make sure everything looks correct once they have been deployed. |
155 | | -
|
156 | | - - Some common problems that you should check for: |
157 | | - - Make sure all plots appear! (*you may want to sign out of your Plotly account to ensure you didn't accidentally embed private plots) |
158 | | - - There are no empty notebook cells |
159 | | - - The thumbnail image appears on: https://plot.ly/python/ |
160 | | -
|
161 | | -## Search |
162 | | -
|
163 | | -We now have search via algolia implemented on our index and reference documentation pages! Please refer to our [make README](https://github.com/plotly/graphing-library-docs/blob/master/make_instructions.txt) for more information on how search works and instructions on how to update or edit Plotly search indices. |
164 | | -
|
165 | | -Thanks for contributing to our documentation!! |
| 1 | +Plotly is no longer modifying or actively maintaining this documentation. |
0 commit comments