Readme for Figure Factory Creation #833
Conversation
|
I'll take a look! |
Thanks. Man, don't know why the tests keep failing |
|
@Kully they're failing on master too - can you make a pr to remove the offline test that signs into stage. It's pretty unstable/fails pretty consistently |
|
@Kully is this pr for the presentation file as well? |
No, that was from before when I added it to one of my branches to move from one branch to another. We can delete that file. |
plotly/Make_a_FigureFactory.md
Outdated
| @@ -0,0 +1,113 @@ | |||
| # Add Your Figure Factory to the Plotly [Python Library](https://plot.ly/python/) | |||
There was a problem hiding this comment.
I would say: Add a Figure Factory to...
plotly/Make_a_FigureFactory.md
Outdated
| 2. Checkout a new branch and give it an appropriate name. | ||
|
|
||
| ``` | ||
| $ git checkout -b "my-new-ff" |
plotly/Make_a_FigureFactory.md
Outdated
| ``` | ||
|
|
||
| ## Create A figure_factory file | ||
| 1. Creating python file and updating `__init__.py` |
There was a problem hiding this comment.
we should keep all the directions in the same tense so
Create A figure_factory file
- Create a python file and update
__init__.py
There was a problem hiding this comment.
you could probably split this step into 2 steps:
creating a python file and updating init.py
plotly/Make_a_FigureFactory.md
Outdated
| ## Create A figure_factory file | ||
| 1. Creating python file and updating `__init__.py` | ||
|
|
||
| You are now ready to start writing your code. Begin by moving to the `plotly.figure_factory` directory in the `plotly.py` repo. Notice that there is an `__init__.py` file as well as a bunch of `_figure_factory_chart.py` files in this directory. Each type of unique plotly chart gets its own python file, and the name of each python file is found in the `__init__.py` file. |
There was a problem hiding this comment.
rm You are now ready to start writing your code.
The directions might be a little easier to follow if they're more straight forward (i.e. more step by step and less conversational)
There was a problem hiding this comment.
Each type of unique plotly chart gets its own python file
That's not really true, not each type of unique plotly chart but rather each figure factory chart. I think this is important to distinguish so people don't think they can edit a non-figure factory chart type from this repo (and end up looking for the scatter python file for instance).
There was a problem hiding this comment.
i'll clarify, thank you
plotly/Make_a_FigureFactory.md
Outdated
| ... | ||
| ``` | ||
|
|
||
| If you want to make, for example, a chart called `foo`, then you must create a python file `_foo.py` and then add the following line to the end of `__init__.py`: |
There was a problem hiding this comment.
I think it makes more sense for step 1 to be
create _foo.py
step 2 is then add _foo.py to init.py
plotly/Make_a_FigureFactory.md
Outdated
| # return fig | ||
| ``` | ||
|
|
||
| You _must_ include what is known as a documentation string or doc string in your function, which is just a block string taht contains useful information about what the function does, the arguments of the function and their descriptions, and examples of this function in use. The doc string is displayed when the help method is run by a user: `help(create_foo)` or `create_foo?` in Jupyter. |
There was a problem hiding this comment.
You must include a documentation string in your function. A doc string is a block string that contains useful information about what the function does, the arguments of the function and their descriptions, and examples of this function in use. The doc string is displayed when the help method is run by a user: help(create_foo) or create_foo? in python.
There was a problem hiding this comment.
*** (help works globally in python- not just jupyter)
plotly/Make_a_FigureFactory.md
Outdated
|
|
||
| You _must_ include what is known as a documentation string or doc string in your function, which is just a block string taht contains useful information about what the function does, the arguments of the function and their descriptions, and examples of this function in use. The doc string is displayed when the help method is run by a user: `help(create_foo)` or `create_foo?` in Jupyter. | ||
|
|
||
| The parameters are listed in the doc string with the format `:param (param_type) param_name: description.` Afterwards, you must include Examples which demonstrate the different capabilities and features of the function. For more information on proper doc string syntax see [PEP-257 page](https://www.python.org/dev/peps/pep-0257/). |
plotly/Make_a_FigureFactory.md
Outdated
|
|
||
| The parameters are listed in the doc string with the format `:param (param_type) param_name: description.` Afterwards, you must include Examples which demonstrate the different capabilities and features of the function. For more information on proper doc string syntax see [PEP-257 page](https://www.python.org/dev/peps/pep-0257/). | ||
|
|
||
| After the doc string, you may write the main code of your function, which should result in returning the `fig`. Users will use your function in the following way: |
There was a problem hiding this comment.
After the doc string, you will add the main code of your function, which should result in returning the fig.
plotly/Make_a_FigureFactory.md
Outdated
|
|
||
| ## Push to GitHub | ||
|
|
||
| When you are finally finished your first draft of your figure factory, it is time to push it to the cloud and to get feedback from the Plotly team and other voluntary GitHub users. After you have added and commited all of your changes on the local branch, push the changes to a new remote branch on Git: |
There was a problem hiding this comment.
not 100% sure what:
it is time to push it to the cloud
means.
Shouldn't we explain how to create a pr. They want to push their code to their remote github branch.
There was a problem hiding this comment.
When you have finished the first draft of your figure factory, it is time to create a pull request for the Plotly team to review.
plotly/Make_a_FigureFactory.md
Outdated
| $ git push origin my-new-ff | ||
| ``` | ||
|
|
||
| Thank you for reading and thanks for contributing to Plotly's Graphing Library! |
There was a problem hiding this comment.
may want to link the general plotly.py contribution instructions as well
plotly/Make_a_FigureFactory.md
Outdated
| @@ -0,0 +1,143 @@ | |||
| # Add A Figure Factory to the Plotly [Python Library](https://plot.ly/python/) | |||
|
|
|||
| If you have ever wanted to contribute to the Plotly Python Library by adding a new chart type we don't have, now you can! This README will help you get started cloning the plotly.py repo, forking a new branch, creating a new figure factory, and creatng a new Pull Request to get feedback for merging. Just follow all these steps and you'll be ready to go. | |||
There was a problem hiding this comment.
changes look good! I'm wondering if it would be better to start out describing/clarifying the differences between figure factories (wrappers around plotly.js charts to create a new chart type) and plotly.graph_objs?
|
@cldougl okay, I added a blurb about figurefactories and py.graph_objs |
|
Relocated to #844 and closing for duplicate PR reasons. |
@chriddyp @cldougl Can one of you proof read my README? Shall I change the name of the file to README? Leave in the same directory?