You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
11
+
2. Check your ruby version with `$ ruby --version`. We recommend using `version 2.3.3` or the same ruby version as GitHub Pages: https://pages.github.com/versions/. Note that[RVM](https://rvm.io/rvm/install) is helpful for installing and managing ruby versions.
12
12
13
-
3. Install bundler and a couple dependencies from the gemfile:
13
+
3. Install bundler and a couple of dependencies from the Gemfile:
14
14
15
15
```
16
16
$ gem install bundler
17
17
$ bundle install
18
18
19
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/).
20
+
<b>IMPORTANT</b> If not using bundler and the Gemfile, install the same jekyll version [as used by GitHub Pages](https://pages.github.com/versions/).
21
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`
22
+
## Create Python Documentation
23
+
Our python tutorials are written as [jupyter notebooks](https://jupyter.readthedocs.io/en/latest/running.html) (`.ipynb` files).
24
+
##### In `documentation/_posts/python/`
25
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.
26
+
2.`cd` into the folder you created and run `jupyter notebook`
27
+
-Using 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
28
3. Base your tutorial structure off of one of our existing tutorials (i.e. `documentation/_posts/python/table/table.ipynb`)
29
29
4. The first cell should be a markdown cell with the following text:
30
30
@@ -35,7 +35,7 @@ Our python tutorials are written in [ipython notebooks](http://ipython.org/noteb
35
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
36
```
37
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:
38
+
5. **If** you're adding a doc about a new feature, the second and third cells should 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
39
- markdown cell:
40
40
```
41
41
#### Version Check
@@ -49,10 +49,10 @@ Our python tutorials are written in [ipython notebooks](http://ipython.org/noteb
49
49
```
50
50
51
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.
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 make headers as informative and concise as possible. Furthermore, capitalize all headers (except for `code`), e.g. `#### Basic Line Chart`.
53
+
- Order examples from basic to advanced.
54
54
- Run examples with user: `PythonPlotBot`
55
-
- Keep import order consistent and import plotly packages first, then a space, then additional packages. For example:
55
+
- Keep import order consistent and import plotly packages first, then skip a line, and import additional packages. For example:
56
56
57
57
```
58
58
import plotly.plotly as py
@@ -62,24 +62,23 @@ Our python tutorials are written in [ipython notebooks](http://ipython.org/noteb
62
62
import numpy as np
63
63
```
64
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 :) )
65
+
- Try and write all of the code for a given example in a *single* jupyter 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 it rather than pasting a large chunk of data in the tutorial. Using random data is okay for some examples too :)
67
67
68
-
7. The last content cell of your notebook should be a markdown cell with:
68
+
7. The last cell of your notebook should be a markdown cell containing:
69
69
70
70
```
71
71
#### Reference
72
72
See https://plot.ly/python/reference/##heatmap for more information and chart attribute options!
73
73
```
74
74
75
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/)!
76
+
page](https://plot.ly/python/reference/)
77
+
and/or a help call:
78
+
`help(FF.create_table)` (the latter applies to documentation on FigureFactory functions).
77
79
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.)
80
+
8. Convert your .ipynb file to an .html file by adding the following code snippet as the last cell of your notebook (publisher cell):
81
+
- Replace `your-tutorial-chart` with the type of chart you're creating in the tutorial;
83
82
- 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
83
85
84
```
@@ -98,40 +97,40 @@ Our python tutorials are written in [ipython notebooks](http://ipython.org/noteb
98
97
language='python',
99
98
# page_type='example_index', // note this is only if you want the tutorial to appear on the main page: plot.ly/python
- See additional options [HERE](https://github.com/plotly/documentation/blob/source-design-merge/_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.
110
+
- See additional options [here](https://github.com/plotly/documentation/blob/source-design-merge/_includes/documentation_eg.html#L1)
111
+
- `order` defines the order in which the tutorials appear online. Please take a look at https://plot.ly/python/ and order your tutorial next to similar chart types. <b>Note</b> that `order` can be a float.
112
+
- `uses_plotly_offline` is an optional argument, set to `True` if you're creating an offline doc.
114
113
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.
114
+
9. Now we can upload/download jupyter (ipython) notebooks to Plotly!!!
115
+
- There is a button in the side navigation bar of the python docs that users can click to see the notebook, download it, and run it to follow along with the documentation.
117
116
- 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:
117
+
- Here are step-by-step instructions on how to enable the `Download THIS Notebook` button:
119
118
1. Copy the notebook from the folder. For example from the [bubble folder](https://github.com/plotly/documentation/tree/source-design-merge/_posts/python/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.
119
+
2. Run `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 them from `.ipynb` to `html`. We do not need to upload this. _Do not remove this cell from the .ipynb in the doc repo_.) Save.
121
120
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.
121
+
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 above.
123
122
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.
123
+
10. Add thumbnail images:
124
+
- Thumbnail images should be named `your-tutorial-chart.jpg` and be **exactly** 160px X 160px.
125
+
- 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.
- 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
130
+
- 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
131
133
-
##### In the terminal in `documentation`
134
-
9. Make a PR
132
+
##### Back in the terminal in `documentation/`
133
+
11. Submit a PR
135
134
136
135
- Ready for your changes to be reviewed? Make a pull request against the `source-design-merge` branch!
137
136
Create a feature branch and use `git status` to list changed files.
@@ -148,14 +147,14 @@ Our python tutorials are written in [ipython notebooks](http://ipython.org/noteb
148
147
```
149
148
- Visit the [documentation repo](https://github.com/plotly/documentation) and open a pull request against the `source-design-merge` branch. You can then tag **@cldougl** and **@bcdunbar** for a review.
150
149
151
-
10. To proof your work follow these steps: https://github.com/plotly/documentation/blob/source/Contributing.md#rendering-the-pages-locally
150
+
12. To proof your work follow these steps: https://github.com/plotly/documentation/blob/source/Contributing.md#rendering-the-pages-locally
152
151
153
152
##### 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 by either **@cldougl** or **@bcdunbar**.
153
+
13. 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 by either **@cldougl** or **@bcdunbar**.
155
154
156
155
- 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
156
+
- Make sure all plots appear! (You may want to sign out of your Plotly account to ensure you didn't accidentally embed private plots.)
157
+
- There are no empty notebook cells.
159
158
- The thumbnail image appears on: https://plot.ly/python/
0 commit comments