diff --git a/Contributing.md b/Contributing.md index 711c5f7e8e30..05500a18df3f 100755 --- a/Contributing.md +++ b/Contributing.md @@ -1,36 +1,42 @@ -## Repo Organization +# Repo Organization + Edit or add files in the `_posts` folder in the [source-design-merge](http://github.com/plotly/documentation/tree/source-design-merge) branch. ## Clone the Repo and Install Dependencies + 1. Clone the repo and then check out the source-design-merge branch: - ``` - $ git clone https://github.com/plotly/documentation.git - $ git fetch origin - $ git checkout source-design-merge - ``` +```sh +git clone git@github.com:plotly/documentation.git +git fetch origin +git checkout source-design-merge +``` -2. Check Ruby version `$ ruby --version`. We recommend using 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. +2. Check Ruby version `$ ruby --version`. We recommend using 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. 3. Install bundler and dependencies from the `gemfile`: - ``` - $ gem install bundler - $ bundle install - ``` -Note these dependencies should be the same version that gh-pages is using: https://pages.github.com/versions/ . +```sh +gem install bundler +bundle install +``` + +Note these dependencies should be the same version that [gh-pages](https://pages.github.com/versions/) is using. 4. When we deploy, a function is run to update the plot schema. To do this successfully you have to make sure you have the `requests` python package: `pip install requests` ## Making Changes -- For information about editing **plotly.js** docs see: https://github.com/plotly/documentation/blob/source-design-merge/_posts/plotly_js/README.md + +- For information about editing **plotly.js** docs see: https://github.com/plotly/documentation/blob/source-design-merge/_posts/plotly_js/README.md - For information about editing **python** docs see: https://github.com/plotly/documentation/blob/source-design-merge/_posts/python/README.md - For information about editing **R** docs see: https://github.com/plotly/documentation/blob/source-design-merge/_posts/r/README.md - For information about editing chart studio documentation found at [https://help.plot.ly/tutorials/](https://help.plot.ly/tutorials/) please see this repo: [https://github.com/plotly/plotly.github.io](https://github.com/plotly/plotly.github.io) ## Render Changes Locally + Please **ALWAYS** locally serve the docs and check your changes before committing updates. -1. To serve the docs locally, in the documentation repo run: `$ bundle exec jekyll serve --config _config_dev.yml` + +1. To serve the docs locally, in the documentation repo run: `bundle exec jekyll serve --config _config_dev.yml` 2. Visit the pages at: [http://localhost:4000/python/](http://localhost:4000/python/) 3. When you make changes, jekyll should automatically regenerate for you. Read the messages in your terminal to check it out @@ -40,7 +46,7 @@ excluding folders in the `_config_dev.yml` file. For example, change `_config_dev.yml` to this: -``` +```yml staticurl: http://localhost:4000/all_static exclude: [_posts/ggplot2, _posts/julia, _posts/matlab, _posts/matplotlib, _posts/nodejs, _posts/r] # [_posts/python,] ``` @@ -49,7 +55,7 @@ and you'll only load the files in `_posts/python`. Change it to this -``` +```yml staticurl: http://localhost:4000/all_static exclude: [] ``` @@ -61,12 +67,12 @@ Ready for your changes to be reviewed? Make a pull request against the `source-d Create a feature branch and use `git status` to list changed files. (Make sure that the feature branch is a branch off from `source-design-merge` local branch in your machine and not from any other previously worked branch). -``` +```sh git checkout -b your_feature_branch git status ``` Add, commit, and push the files that you'd like to add to your pr: -``` +```sh git add file-a git add file-b git commit -m 'message about your changes' diff --git a/README.md b/README.md index e1352c26b8a3..6f915c51ad45 100755 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -plotly's github-pages api documentation repository +# Plotly's github-pages api documentation repository - the [source-design-merge](http://github.com/plotly/documentation/tree/source-design-merge) branch is where edits and contributions are made - the [gh-pages](http://github.com/plotly/documentation/tree/gh-pages) branch is the deploy branch, automatically updated with `$ rake deploy` inside [source-design-merge](http://github.com/plotly/documentation/tree/source-design-merge) diff --git a/_posts/plotly_js/README.md b/_posts/plotly_js/README.md index 23dcb5e7527b..bfd8f95026db 100644 --- a/_posts/plotly_js/README.md +++ b/_posts/plotly_js/README.md @@ -1,28 +1,34 @@ # Contribute to Plotly's [Javascript Documentation](https://plot.ly/javascript/) + ## Initial Steps: + 1. Clone the repo and then check out the source-design-merge branch: - ``` - $ git clone git@github.com:plotly/documentation.git - $ git fetch origin - $ git checkout source-design-merge + ```sh + git clone git@github.com:plotly/documentation.git + git fetch origin + git checkout source-design-merge ``` -2. Check Ruby version `$ ruby --version`. We recommend using 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. +2. Check Ruby version `$ ruby --version`. We recommend using 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. 3. Install bundler and a couple dependencies from the gemfile: - ``` - $ gem install bundler - $ bundle install +```sh +gem install bundler +bundle install +``` - ``` IMPORTANT -If not using bundler and the gemfile, [install the same jekyll version that Github Pages is using](https://pages.github.com/versions/). ## Create Plotly.js Documentation: -Our javascript tutorials are written in HTML files with embeded [codepen](http://codepen.io/plotly/) examples. + +Our javascript tutorials are written in HTML files with embedded [codepen](http://codepen.io/plotly/) examples. + ##### In `documentation/_posts/plotly_js` -1. Create a folder titled with the chart type or topic you're adding to the documentation (i.e. `bar`) + +1. Create a folder titled with the chart type or topic you're adding to the documentation (i.e. `bar`) + 2. `cd` into the folder you created and create an html index file labeled: `yyyy-mm-dd-chart_type_plotlyjs_index.html`. Copy the index file template below and replace with the necessary information pertaining to the doc you are creating. ``` --- diff --git a/_posts/plotly_js/chart-events/events/2017-01-01-order3-1_event_data.html b/_posts/plotly_js/chart-events/events/2017-01-01-order3-1_event_data.html index 3ce80885c7a2..3058cd89485f 100644 --- a/_posts/plotly_js/chart-events/events/2017-01-01-order3-1_event_data.html +++ b/_posts/plotly_js/chart-events/events/2017-01-01-order3-1_event_data.html @@ -51,7 +51,7 @@ curveNumber: 2, // index in data of the trace associated with the selected point pointNumber: 2, // index of the selected point lat: 50, // latitude value - lon: -12, // longtitude value + lon: -12, // longitude value data: {/* */}, // ref to the trace as sent to Plotly.plot associated with the selected point fullData: {/* */}, // ref to the trace including all of the default attributes location: // diff --git a/_posts/plotly_js/chart-events/events/2017-01-01-order6_selected_event.html b/_posts/plotly_js/chart-events/events/2017-01-01-order6_selected_event.html index a15047d8578b..5b4b70faeb2f 100644 --- a/_posts/plotly_js/chart-events/events/2017-01-01-order6_selected_event.html +++ b/_posts/plotly_js/chart-events/events/2017-01-01-order6_selected_event.html @@ -7,7 +7,7 @@ sitemap: false arrangement: horizontal markdown_content: | - Here's a simple example using the data returned from the `plotly_selected` event. `plotly_selected` returns event data for all points selected simultaneously. After creating a scatter plot with random data and two histograms that display the x and y distributions of that random data, we can select points by clicking and dragging on the plot. Upon `plotly_selected` the histograms will update to display the distribution of the x and y values of the selected points. The color of the scatter plot will be updated as well to highlight the selected points. For more examples of using `plotly_slected` and `plotly_selecting` events, see: https://plot.ly/javascript/lasso-selection/ + Here's a simple example using the data returned from the `plotly_selected` event. `plotly_selected` returns event data for all points selected simultaneously. After creating a scatter plot with random data and two histograms that display the x and y distributions of that random data, we can select points by clicking and dragging on the plot. Upon `plotly_selected` the histograms will update to display the distribution of the x and y values of the selected points. The color of the scatter plot will be updated as well to highlight the selected points. For more examples of using `plotly_selected` and `plotly_selecting` events, see: https://plot.ly/javascript/lasso-selection/ --- var graphDiv = document.getElementById('graph'); var N = 1000; diff --git a/_posts/plotly_js/fundamentals/2015-11-06-announcement.md b/_posts/plotly_js/fundamentals/2015-11-06-announcement.md index 1fadc26f07a7..a94553e57f3d 100644 --- a/_posts/plotly_js/fundamentals/2015-11-06-announcement.md +++ b/_posts/plotly_js/fundamentals/2015-11-06-announcement.md @@ -11,7 +11,6 @@ language: plotly_js # Plotly.js Open-Source Announcement - November 17, 2015

✨ Announcement ✨ 100% of Plotly's JavaScript charting library is now free and open-source.https://t.co/5bneDRdV98 pic.twitter.com/NADG6eaEmA

— plotly (@plotlygraphs) November 17, 2015
@@ -21,7 +20,7 @@ A growing number of graphing tools and libraries allow anyone to make beautiful, **Today, Plotly is announcing that we have open-sourced plotly.js, the core technology and JavaScript graphing library behind Plotly’s products** (MIT license). It's all out there and free. Any developer can now integrate Plotly’s library into their own applications unencumbered. Plotly.js supports 20 chart types, including 3D plots, geographic maps, and statistical charts like density plots, histograms, box plots, and contour plots. -We’re big fans of collaboration, freedom, and perpetual motion. Open-source has become the de facto distribution for gold-standard scientific and business intelligence software. We want to support, participate in, and amplify this trend. By open-sourcing Plotly's core technology, everyone benefits from peer-review and Plotly's products will continue to be the most cutting-edge offering for exploratory visualization. Plotly.js has the quality, accessibility, and scope to be the charting standard for the Web, but we can only achieve this breadth by working across communities and making the distribution truly unencumbered, portable, and free. +We’re big fans of collaboration, freedom, and perpetual motion. Open-source has become the de facto distribution for gold-standard scientific and business intelligence software. We want to support, participate in, and amplify this trend. By open-sourcing Plotly’s core technology, everyone benefits from peer-review and Plotly’s products will continue to be the most cutting-edge offering for exploratory visualization. Plotly.js has the quality, accessibility, and scope to be the charting standard for the Web, but we can only achieve this breadth by working across communities and making the distribution truly unencumbered, portable, and free. Despite the possibilities that the web offers, the core plotting libraries in scientific software like MATLAB, R, and Python still create static image files rather than dynamic, interactive charts. Many technical and scientific projects still don't embrace web technology because of JavaScript libraries being commercially developed, expensive, narrow in scope, or difficult to learn and use. By open-sourcing Plotly’s easy-to-use, comprehensive library, Plotly hopes to bring the power of interactive plotting to every developer, team, data scientist, and analyst. @@ -105,7 +104,7 @@ The plotly.js roadmap is constantly changing, but 2016 is likely to be focused o If you’re a JavaScript developer, consider taking a look at the plotly.js code on [GitHub](https://github.com/plotly/plotly.js). Submitting Codepen examples to [community.plot.ly](http://community.plot.ly/c/plotly-js) for the documentation is also a great way to contribute. -If you’re an R, Python, MATLAB, or Julia developer please consider contributing to one of the clients on [Plotly's GitHub](http://github.com/plotly/). +If you’re an R, Python, MATLAB, or Julia developer please consider contributing to one of the clients on [Plotly’s GitHub](http://github.com/plotly/). ## Humans behind the project diff --git a/_posts/plotly_js/fundamentals/2016-01-26-modularization.md b/_posts/plotly_js/fundamentals/2016-01-26-modularization.md index e09d368e0dcc..96392b246bd1 100644 --- a/_posts/plotly_js/fundamentals/2016-01-26-modularization.md +++ b/_posts/plotly_js/fundamentals/2016-01-26-modularization.md @@ -17,7 +17,6 @@ January 28, 2016 modularity using a mono-repo, one npm package and several CommonJS require-able modules. - The current era of client-side javascript stands between two major events: the npm-modules explosion is a few years behind us, but wide-spread implementation of native client-side modules by browsers is several years away. @@ -46,8 +45,7 @@ they need. In the past two months, we surveyed library design solutions in an effort to provide the best experience for plotly.js consumers. We hope that our efforts may help maintainers of other client-side libraries make judicious design -choices. We present Plotly's solution to client-side modularization below. - +choices. We present Plotly’s solution to client-side modularization below. ### Problem @@ -89,7 +87,6 @@ important in 2016. Its endorsement by the version 4 of [d3](http://bost.ocks.org/mike/d3-plugin/) may make ES6 module definitions common place for the next generation of large client-side libraries. - ### Possible solution 1 Split up the library's modules into multiple repos, with each module linked to @@ -113,7 +110,6 @@ discarded. - Possible code duplication unless the internal modules become npm packages too (more on that in the next section) - ### Possible solution 2 Another solution to the problem would place all the code under one *mono-repo* @@ -182,7 +178,6 @@ To sum up: pulling it off. - Internal modules are prone to code duplication in the resulting bundles. - ### Possible solution 3 Our solution! @@ -252,8 +247,7 @@ made the `require` statements even cleaner e.g. `require('plotly.js/core')` instead of `require('plotly.js/lib/core')`. But considering the large number of these `lib` files we have, we opt for a `lib` directory in order to not pollute the repo's root. Note that the `"main"` package.json field cannot be set to a -directory (more info [here](Mention -https://github.com/nodejs/node/issues/3953)). +directory (more info [here](https://github.com/nodejs/node/issues/3953). Our solution results in a minor increase in build time, but we feel that the flexibility it allows is well worth the hit. Browserify and webpack both have @@ -281,7 +275,6 @@ appropriately. - Webpack users will need to add [ify-loader](https://github.com/hughsk/ify-loader) to their config file - You can check out our latest (modular) [plotly.js release on GitHub](https://github.com/plotly/plotly.js/releases/tag/v1.5.0). If this is your first time hearing about plotly.js, check out our [gallery and documentation](https://plot.ly/javascript). We just recently open-sourced the project and you can learn more about our decision in our [open-source announcement](https://plot.ly/javascript/open-source-announcement). Thanks for reading! diff --git a/_posts/plotly_js/fundamentals/static-image-export/2016-05-20-static-image.md b/_posts/plotly_js/fundamentals/static-image-export/2016-05-20-static-image.md index 3ecef1002974..af8d31b697e6 100644 --- a/_posts/plotly_js/fundamentals/static-image-export/2016-05-20-static-image.md +++ b/_posts/plotly_js/fundamentals/static-image-export/2016-05-20-static-image.md @@ -19,7 +19,7 @@ You can save plotly graphs to static images and view them in your browser. Consi var d3 = Plotly.d3; var img_jpg= d3.select('#jpg-export'); - // Ploting the Graph + // Plotting the Graph var trace={x:[3,9,8,10,4,6,5],y:[5,7,6,7,8,9,8],type:"scatter"}; var trace1={x:[3,4,1,6,8,9,5],y:[4,2,5,2,1,7,3],type:"scatter"}; @@ -33,16 +33,16 @@ You can save plotly graphs to static images and view them in your browser. Consi // static image in jpg format .then( - function(gd) - { - Plotly.toImage(gd,{height:300,width:300}) - .then( - function(url) - { - img_jpg.attr("src", url); - return Plotly.toImage(gd,{format:'jpeg',height:400,width:400}); - } - ) + function(gd) + { + Plotly.toImage(gd,{height:300,width:300}) + .then( + function(url) + { + img_jpg.attr("src", url); + return Plotly.toImage(gd,{format:'jpeg',height:400,width:400}); + } + ) }); To view this image in your page include following HTML tag: @@ -50,7 +50,6 @@ To view this image in your page include following HTML tag: Height and width of the image can be adjusted by specifying the same in `toImage` call: - Plotly.toImage( gd,{ format:'jpeg', @@ -58,7 +57,6 @@ Height and width of the image can be adjusted by specifying the same in `toImage width:desired_width, }); - You can also save the image using different formats. # Formats Supported @@ -68,8 +66,8 @@ The common image formats: 'PNG', 'JPG/JPEG' are supported. In addition, formats **Note:** It is important to note that any figures containing WebGL traces (i.e. of type scattergl, heatmapgl, contourgl, scatter3d, surface, mesh3d, scatterpolargl, cone, streamtube, splom, or parcoords) that are exported in a vector format like SVG, EPS or PDF will include encapsulated rasters instead of vectors for some parts of the image. ## Saving as PNG ## - img_png.attr("src", url); - Plotly.toImage(gd,{format:'png',height:400,width:400}); + img_png.attr("src", url); + Plotly.toImage(gd,{format:'png',height:400,width:400}); ## Saving as SVG ## img_svg.attr("src", url); diff --git a/_posts/plotly_js/maps/choropleth-maps/2015-08-11-US-pop-by-state-choropleth.html b/_posts/plotly_js/maps/choropleth-maps/2015-08-11-US-pop-by-state-choropleth.html index 1bbec9e29401..7fcb3827fb11 100644 --- a/_posts/plotly_js/maps/choropleth-maps/2015-08-11-US-pop-by-state-choropleth.html +++ b/_posts/plotly_js/maps/choropleth-maps/2015-08-11-US-pop-by-state-choropleth.html @@ -24,7 +24,7 @@ var layout = { - title: '2014 US Popultaion by State', + title: '2014 US Population by State', geo:{ scope: 'usa', countrycolor: 'rgb(255, 255, 255)', diff --git a/style_README.md b/style_README.md index f6b47ad771dd..ecc9bb5dd170 100644 --- a/style_README.md +++ b/style_README.md @@ -1,6 +1,6 @@ # Styles -The styling for this repo is broken up into two different parts: [gulp](https://github.com/plotly/documentation/blob/source-design-merge/gulpfile.js) + browsersync + sass and vanilla css. +The styling for this repo is broken up into two different parts: [gulp](https://github.com/plotly/documentation/blob/source-design-merge/gulpfile.js) + browsersync + sass and vanilla css. It is recommended to use something to create a local server environment such as MAMP Pro which allows you to set virtual hosts (e.g.: http://api.plotly.dev) @@ -16,14 +16,13 @@ Once the repo has been cloned successfully (see [Contributing.md](https://github Generally it's best to work with two instances of terminal, one to use for anything related to `$ jekyll` and then another to keep the `$ gulp` task running. - 1. run `$ jekyll serve --config _config_dev.yml` to create a local server @ http://localhost:4000 that browsersync leverages (see gulpfile.js to adjust as needed) OR -2. run `$ jekyll build --config _config_dev.yml` and leverage a local server @ http://api.plotly.dev through a service like MAMP Pro that browsersync leverages (see gulpfile.js to adjust as needed) -3. run `$ gulp` -4. make any updates to the scss files +1. run `$ jekyll build --config _config_dev.yml` and leverage a local server @ http://api.plotly.dev through a service like MAMP Pro that browsersync leverages (see gulpfile.js to adjust as needed) +2. run `$ gulp` +3. make any updates to the scss files ### markup + scss workflow @@ -55,7 +54,8 @@ When you run a `$ jekyll` you need to update any scss file as jekyll will automa - main.css *(the css conversion of main.scss)* ## Deploying Changes After Editing the SCSS - - Run `gulp build` in the root of the documentation repo after making any scss edits. This will update `main.css` as well as the [verion](https://github.com/plotly/documentation/blob/source-design-merge/_data/cache_bust_css.yml) which is used to prevent css caching. + + - Run `gulp build` in the root of the documentation repo after making any scss edits. This will update `main.css` as well as the [version](https://github.com/plotly/documentation/blob/source-design-merge/_data/cache_bust_css.yml) which is used to prevent css caching. - `git add` the files you've changed as well as the generated `main.css` and `cache_bust_css.yml` files, `git commit -m 'message about update'`, and `git push origin source-design-merge` to add your updates to the repo. - run `rake deploy` to deploy changes.