From 50a91a11cd4f1f1f682022cf9d5add57d12d699e Mon Sep 17 00:00:00 2001 From: Joseph Damiba Date: Fri, 3 Jan 2020 19:12:33 -0500 Subject: [PATCH 1/6] Update Contributing.md Update Contributing.md Update Contributing.md Update Contributing.md Update README.md Update Contributing.md Update Contributing.md Update Contributing.md Update Contributing.md Update Contributing.md Update Contributing.md Update Contributing.md Update Contributing.md Update README.md Update README.md Update README.md updating readme typo fixup --- Contributing.md | 126 ++++++++++--------- _posts/plotly_js/README.md | 246 ++++++++++++++++++++----------------- 2 files changed, 202 insertions(+), 170 deletions(-) diff --git a/Contributing.md b/Contributing.md index 0d5ca9bf62b5..71fe38d379bf 100755 --- a/Contributing.md +++ b/Contributing.md @@ -1,10 +1,50 @@ -# Repo Organization +# Contributing to Plotly's Graphing Libraries Documentation -Edit or add files in the `_posts` folder in the [source-design-merge](http://github.com/plotly/documentation/tree/source-design-merge) branch. +Plotly welcomes contributions to its [open-source graphing libraries documentation](https://plot.ly/graphing-libraries) from its community of users. -## Clone the Repo and Install Dependencies +The `source-design-merge` branch of this repository hosts a Jekyll application hosted on GitHub Pages that serves Plotly's graphing libraries documentation. -1. Clone the repo and then check out the source-design-merge branch: +The index page for the documentation website is located at https://plot.ly/graphing-libraries. + +### plotly.js + +Please be aware that **only the content of Plotly's JavaScript graphing library documentation** (hosted at https://plot.ly/javascript) is contained in this repository. You can find the content in the `_posts/plotly_js` directory. + +For information about editing **plotly.js** documentation [click here](https://github.com/plotly/documentation/blob/readme-updates/_posts/plotly_js/README.md). + +### plotly.py + +The content for Plotly's Python graphing library documentation (hosted at https://plot.ly/python) **IS NOT** contained in this repository. It is contained in the `plotly.py` repository at https://github.com/plotly/plotly.py/tree/master/doc and is cloned into this repository at build time. + +For information about editing **plotly.py** documentation [click here] (https://github.com/plotly/plotly.py/blob/master/doc/README.md). + +### plotly.r + +The content for Plotly's R graphing library documentation (hosted at https://plot.ly/r) **IS NOT** contained in this repository. It is contained in the `plotly.r-docs` repository at https://github.com/plotly/plotly.r-docs/ and is cloned into this repository at build time. + +For information about editing Plotly's **R** documentation [click here](https://github.com/plotly/plotly.r-docs/blob/master/README.md). + +**For more information about the build process, inspect the CircleCI configuration file in this repository at https://github.com/plotly/documentation/blob/source-design-merge/.circleci/config.yml.** + +## Contribute Quickly to Plotly's JavaScript Graphing Library Documentation + +To quickly make a contribution to Plotly's JavaScript graphing libraries documentation, simply submit a pull request with the change you would like to suggest to the `source-design-merge` branch of this repository. + +The easiest way to do this is to follow the `Edit this page on GitHub` link at the top right of the page you are interested in contributing to: + +![Screen Shot 2020-01-07 at 12 45 39 PM](https://user-images.githubusercontent.com/1557650/71916356-bfe53800-314b-11ea-92b6-eb763037f6d5.png) + +**You don't have to worry about breaking the site when you submit a pull request!** This is because your change will not be merged to production immediately. A Plotly team member will first perform a code review on your pull request. + +## How To Get The Application Working Locally + +For more extensive changes to Ploty's JavaScript documentation, we suggest getting the Jekyll application which builds the site to run locally so that you can test your changes as you develop them. + +This involves cloning the repository and installing its dependencies: [Git](https://git-scm.com/), [Ruby]((https://www.ruby-lang.org/en/), [Jekyll](https://jekyllrb.com/), and the [Python `requests` package](https://pypi.org/project/requests/). + +1. Use [`git`](https://git-scm.com/) to [clone](https://git-scm.com/docs/git-clone) the public `plotly/documentation` repository. Then [check out] (https://git-scm.com/docs/git-checkout) the source-design-merge branch of the `git` repository. + +To do so, run the following commands in your terminal: ```sh git clone git@github.com:plotly/documentation.git @@ -12,80 +52,52 @@ git fetch origin git checkout source-design-merge ``` -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. - -3. Install bundler and dependencies from the `Gemfile`: +Running `git status` in your terminal should then output the following: ```sh -gem install bundler -bundle install +On branch source-design-merge +Your branch is up to date with 'origin/source-design-merge'. + +nothing to commit, working tree clean ``` -Note these dependencies should be the same version that [gh-pages](https://pages.github.com/versions/) is using. +2. Download Ruby and check your `Ruby` version by running the `ruby --version` command in your terminal. -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` +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. -## Making Changes +3. Download Jekyll and check your Jekyll version by running the `jekyll -v` command in your terminal. We recommend using the same ruby version as [gh-pages](https://pages.github.com/versions/). -- 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) +4. Install bundler and dependencies from the Jekyll applicaton's [`Gemfile`](https://github.com/plotly/documentation/blob/source-design-merge/Gemfile) by running the following commands in your terminal: + +```sh +gem install bundler +bundle install +``` -## Render Changes Locally +Note these dependencies should be the same version that [gh-pages](https://pages.github.com/versions/) is using. -Please **ALWAYS** locally serve the docs and check your changes before committing updates. +5. When Plotly deploys its graphing libraries documentation to GitHub pages, a function is run to simultaneously update the graphing libraries plot schema in order to keep the two in sync. To do this successfully you have to make sure you have Python and the `requests` Python package installed in your local development environment: `pip install requests`. -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 +6. Serve the Jekyll application: `bundle exec jekyll serve --config _config_dev.yml`. +7. Visit the pages at: [http://localhost:4000/](http://localhost:4000) +8. When you make changes, Jekyll should automatically regenerate the application for you. Read the messages in your terminal to check it out. -There are a TON of posts in here, so rendering can take up to -thirty minutes! You can *limit* the number of posts that render by -excluding folders in the `_config_dev.yml` file. +There are a TON of posts in here, so rendering can take up to thirty minutes! You can *limit* the number of posts that render by [excluding folders](https://jekyllrb.com/docs/configuration/options/) from being served using custom Jekyll configuration options. -For example, change `_config_dev.yml` to this: +To do so, create a `_config_personal.yml` file: ```yml staticurl: http://localhost:4000/all_static -exclude: [_posts/ggplot2, _posts/julia, _posts/matlab, _posts/matplotlib, _posts/nodejs, _posts/r] # [_posts/python,] +exclude: [_posts/ggplot2, _posts/julia, _posts/matlab, _posts/matplotlib, _posts/nodejs, _posts/r, posts/python] # [_posts/plotly_js,] ``` -and you'll only load the files in `_posts/python`. +and you'll only load the files in `_posts/plotly_js`. -Change it to this +Change it to this: ```yml staticurl: http://localhost:4000/all_static exclude: [] ``` -and it'll load everything. - -## Make a PR -Ready for your changes to be reviewed? Make a pull request against the `source-design-merge` branch! -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' -git push origin your_feature_branch -``` -Visit the [documentation repo](https://github.com/plotly/documentation) and open a pull request against the `source-design-merge` branch. - -After your PR has been reviewed and approved, you can merge it into the `source-design-merge` branch! Your changes haven't been deployed yet so they won't be online. That said, be sure to check them after they have been deployed. - -## Search - -We now have search via algolia implemented on our index and reference documentation pages! Please refer to our [make README](https://github.com/plotly/documentation/blob/source-design-merge/make_instructions.txt) for more information on how search works and instructions on how to update or edit Plotly search indices. - -## Style Edits - -Please refer to our [Styles README](https://github.com/plotly/documentation/blob/source-design-merge/style_README.md) +and it'll load everything. \ No newline at end of file diff --git a/_posts/plotly_js/README.md b/_posts/plotly_js/README.md index b8329eb53e78..07385f5a05c1 100644 --- a/_posts/plotly_js/README.md +++ b/_posts/plotly_js/README.md @@ -1,131 +1,151 @@ # Contribute to Plotly's [JavaScript Documentation](https://plot.ly/javascript/) -## Initial Steps: +Plotly welcomes contributions to its [open-source JavaScript graphing libraries documentation](https://plot.ly/javascript) from its community of users. -1. Clone the repo and then check out the source-design-merge branch: +Our JavaScript tutorials are written in HTML files in the `_posts/plotly_js` directory of this repository. - ```sh - git clone git@github.com:plotly/documentation.git - git fetch origin - git checkout source-design-merge - ``` +## Contribute Quickly to Plotly's JavaScript Graphing Library Documentation + +To quickly make a contribution to Plotly's JavaScript graphing libraries documentation, simply submit a pull request with the change you would like to suggest to the `source-design-merge` branch of this repository. This can be done using the GitHub graphical user interface at https://github.com/plotly/documentation. -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. +The easiest way to do this is to follow the `Edit this page on GitHub` link at the top right of the page you are interested in contributing to: -3. Install bundler and a couple dependencies from the gemfile: +![Screen Shot 2020-01-07 at 12 45 39 PM](https://user-images.githubusercontent.com/1557650/71916356-bfe53800-314b-11ea-92b6-eb763037f6d5.png) -```sh -gem install bundler -bundle install -``` +**You don't have to worry about breaking the site when you submit a pull request!** This is because your change will not be merged to production immediately. A Plotly team member will first perform a code review on your pull request in order to ensure that it definitely increases the health of Plotly's graphing libraries codebase. + +## Develop Locally + +For contributions such as new example posts, we recommend setting up a local development environment so that you can test your changes as you work on them. -IMPORTANT -If not using bundler and the gemfile, [install the same jekyll version that GitHub Pages is using](https://pages.github.com/versions/). +**See the `How To Get The Application Working Locally` section of the [Contributing Guide](https://github.com/plotly/documentation/blob/readme-updates/Contributing.md) to learn how to clone this repository to your local development environment and install its dependencies.** -## Create Plotly.js Documentation: +Then follow these instructions to create or modify a new post. If the post is the first of its chart type, you need to create an index page for it first. -Our javascript tutorials are written in HTML files with embedded [codepen](http://codepen.io/plotly/) examples. +## Create An Index Page For A New Chart Type: -##### In `documentation/_posts/plotly_js` +If you are documenting a new chart type, then you need to create an index page for it before creating the actual example page. -1. Create a folder titled with the chart type or topic you're adding to the documentation (i.e. `bar`) +1. In `documentation/_posts/plotly_js`, 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. - ``` - --- - name: Add-Chart-Type-or-Topic - permalink: javascript/add-chart-type-or-topic/ - description: How to make a D3.js-based add-chart-type-or-topic in javascript. Add an additional sentence summarizing chart-type or topic. - layout: base - thumbnail: thumbnail/add-chart-type-or-topic.jpg *MORE INFO ON ADDING THUMBNAILS BELOW - language: plotly_js - page_type: example_index - display_as: **SEE BELOW - order: ***SEE BELOW - markdown_content: | - indented content in markdown format which will prefix an example ****SEE BELOW - --- - {% assign examples = site.posts | where:"language","plotly_js" | where:"suite","add-chart-type-or-topic"**** | sort: "order" %} +2. `cd` into the folder you created and create an HTML index file for the chart type named: `yyyy-mm-dd-chart_type_plotly_js_index.html`. Copy the index file template below. Make sure to replace placeholder text! +``` +--- +name: Add-Chart-Type-or-Topic +permalink: javascript/add-chart-type-or-topic/ +description: How to make a D3.js-based add-chart-type-or-topic in javascript. Add an additional sentence summarizing chart-type or topic. +layout: langindex +thumbnail: thumbnail/mixed.jpg +language: plotly_js +page_type: example_index +display_as: **SEE BELOW +order: 5 +--- + {% assign examples = site.posts | where:"language","plotly_js" | where:"suite","add-chart-type-or-topic"| sort: "order" %} {% include posts/auto_examples.html examples=examples %} - ``` - - \*\*`display_as` sets where your tutorial is displayed - - 'basic' = https://plot.ly/javascipt/#basic-charts - - 'statistical' = https://plot.ly/javascipt/#statistical-charts - - 'scientific' = https://plot.ly/javascipt/#scientific-charts - - 'financial' = https://plot.ly/javascipt/#financial-charts - - 'maps' = https://plot.ly/javascipt/#maps - - '3d_charts' = https://plot.ly/javascipt/#3d-charts - - See additional options [HERE](https://github.com/plotly/documentation/blob/source-design-merge/_includes/documentation_eg.html#L1) - - \*\*\* `order` defines the order in which the tutorials appear in each section on plot.ly/javascript. Please take a look at https://plot.ly/javascript/ and order your tutorial next to similar chart types. Note `order` can be a float. - - \*\*\*\* `markdown_content` is rendered directly above the examples. In general, it is best to *avoid* paragraph-formatted explanation and let the simplicity of the example speak for itself, but that's not always possible. Take note that headings in this block *are* reflected in the sidebar. - -3. Create a Codepen example. Use Plotly's Codepen account to create an example that clearly demonstrates the feature that you're discussing in the doc. - -4. Add an HTML file for each example with the codepen example embedded within. The codepen example must be embedded with `https` (not `http`). The HTML file should have a header (template below), followed by the javascript code used in the codepen example. - ``` - --- - name: Basic Bar Chart ** - plot_url: https://codepen.io/plotly/embed/74a638752a41ac9672a05f628e4ddaff/?height=500&theme-id=15263&default-tab=result - language: plotly_js - suite: bar - order: 1 ** - sitemap: false - arrangement: horizontal - --- - var data = [ - { - x: ['giraffes', 'orangutans', 'monkeys'], - y: [20, 14, 23], - type: 'bar' - }The - ]; - - Plotly.newPlot('myDiv', data); - ``` - -6. Best Practices: - - Set `plot_url:` to the embedded codepen example with the `default-tab=result` - - Now we have an awesome navigation bar on the left side of our tutorial pages. The navigation bar displays the `name`** in the `order`** so add a `name` for each example and try to make `name`s as informative and concise as possible. Ex: `Basic Bar Chart` - - `order` examples from basic -> advanced. - - Try to use "real" data, to make the examples realistic and interesting. Avoid including large datablocks in the tutorial by uploading the datafile to https://github.com/plotly/datasets. Importing data rather than pasting a large chunk of data in the tutorial creates a cleaner example. (Using random data is okay for some examples too :) ) - -8. Add Thumbnail Images - - Thumbnail images should named `your-tutorial-chart.jpg` and be *EXACTLY* 160px X 160px - - 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. - - Use images.plot.ly for adding new images. - - Log-in here: https://661924842005.signin.aws.amazon.com/console - - Username: Plotly\_Editors - - From the Amazon Web Services Console select S3 (Scalable Storage in the Cloud) then select plotly-tutorials -> plotly-documentation -> thumbnail - - Now from All Buckets /plotly-tutorials/plotly-documentation/thumbnail select the Actions dropdown and upload your .jpg file - -##### In the terminal in the `documentation` repo -9. Make a PR +``` + - Make sure to update `_includes/posts/documentation_eg.html` with the new chart type! + + - Index pages for chart categories must have `order: 5`. +## Create A New Example Post: + +1. In the folder containing the examples for the chart type you are writing documenation for, create a file named: `yyyy-mm-dd-example-title.html`. + +2. Copy the example post template below and write JavaScript code to demonstrate the feature you are documenting. + - If `plot_url` front-matter is not present, then the resulting chart will be displayed inline and a `Try It Codepen` button will be automatically generated. + - If `plot_url` front-matter is present, then the URL given will be embedded in an `iframe` below the example. +``` +--- +description: How to make a D3.js-based bar chart in javascript. Seven examples of +grouped, stacked, overlaid, and colored bar charts. +display_as: basic +language: plotly_js +layout: base +name: Bar Charts +order: 3 +page_type: example_index +permalink: javascript/bar-charts/ +redirect_from: javascript-graphing-library/bar-charts/ +thumbnail: thumbnail/bar.jpg **MORE INFO ON ADDING THUMBNAILS BELOW +markdown_content: | + indented content in markdown format which will prefix an example ****SEE BELOW +--- +var data = [ + { + x: ['giraffes', 'orangutans', 'monkeys'], + y: [20, 14, 23], + type: 'bar' + }The +]; + +Plotly.newPlot('myDiv', data); +``` + +- `display_as` sets where your tutorial is displayed. Make sure to update `_includes/posts/documentation_eg.html` with the new chart type!: + - 'file_settings' = https://plot.ly/javascript/plotly-fundamentals + - 'basic' = https://plot.ly/javascript/basic-charts + - 'statistical' = https://plot.ly/javascript/statistical-charts + - 'scientific' = https://plot.ly/javascript/scientific-charts + - 'financial' = https://plot.ly/javascript/financial-charts + - 'maps' = https://plot.ly/javascript/maps + - '3d_charts' = https://plot.ly/javascript/3d-charts + - See additional options [HERE](https://github.com/plotly/documentation/blob/b583373f41a5efa78272e0d1cf0ba00ac23458a3/_includes/posts/documentation_eg.html#L1) + + - `order` defines the order in which the tutorials appear in each section on plot.ly/javascript. + - Note The `order` of posts within a `display_as` must be a set of consecutive integers (i.e. [1, 2, 3, 4, 5, 6, ...]). + - If a post has an `order` less than 5, it **MUST** also have the `page_type: example_index` front-matter so that it gets displayed on the index page. + + - `markdown_content` is rendered directly above the examples. In general, it is best to *avoid* paragraph-formatted explanation and let the simplicity of the example speak for itself, but that's not always possible. Take note that headings in this block *are* reflected in the sidebar. + + - Thumbnail images should named `your-tutorial-chart.jpg` and be *EXACTLY* 160px X 160px. + - posts in the following `display_as` categories **MUST** have a thumbnail + - 'file_settings' = https://plot.ly/javascript/plotly-fundamentals + - 'basic' = https://plot.ly/javascript/basic-charts + - 'statistical' = https://plot.ly/javascript/statistical-charts + - 'scientific' = https://plot.ly/javascript/scientific-charts + - 'financial' = https://plot.ly/javascript/financial-charts + - 'maps' = https://plot.ly/javascript/maps + - '3d_charts' = https://plot.ly/javascript/3d-charts + - 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. + - Use images.plot.ly for adding new images. The password is in the Plotly 1Password Engineering Vault. + - Log-in here: https://661924842005.signin.aws.amazon.com/console + - From the Amazon Web Services Console select S3 (Scalable Storage in the Cloud) then select plotly-tutorials -> plotly-documentation -> thumbnail + - Now from All Buckets /plotly-tutorials/plotly-documentation/thumbnail select the Actions dropdown and upload your .jpg file + +## Modify An Existing Post: + +1. Find the post you want to modify in `_posts/plotly_js`. Then, open the HTML file that contains that post and modify either the front-matter or the JavaScript. + +# Best Practices: + - `order` examples from basic to advanced + - avoid the use of global JavaScript variables for `data` and `layout`. + - make the chart display in a DOM element named `myDiv` + - use the `.newPlot()` function + - use "real" data to make the examples realistic and useful for users. + - avoid using random or dummy data as much as humanly possible! Should only be a last resort. + - upload data files to https://github.com/plotly/datasets as importing data rather than pasting a large chunk of data in the tutorial creates a cleaner example. + - use `var config = {mapboxAccessToken: "your access token"};` if your chart requires Mapbox authentication. `"your access token` will replaced by Plotly's private token at build time. In development mode, you will need to create a `_data/mapboxtoken.yml` file and paste Plotly's non-URL restricted Mapbox key into it. This is available in 1Password. + +## Make a Pull Request - Ready for your changes to be reviewed? Make a pull request against the `source-design-merge` branch! - Create a feature branch and use `git status` to list changed files. - ``` - git checkout -b your_feature_branch - git status - ``` - - Add, commit, and push the files that you'd like to add to your PR: - ``` - git add file-a - git add file-b - git commit -m 'message about your changes' - git push origin your_feature_branch - ``` - - 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. - -10. To proof your work follow these steps: https://github.com/plotly/documentation/blob/source/Contributing.md#rendering-the-pages-locally - -##### At https://plot.ly/javascript -11. Your changes haven't been deployed yet so they won't be online. That said, PLEASE visit https://plot.ly/javascipt/your-tutorial and make sure everything looks correct once they have been deployed by either **@cldougl** or **@bcdunbar**. - - - Some common problems that you should check for: - - Make sure all plots/codepen embeds appear! (\*you may want to sign out of your Plotly/codepen account to ensure you didn't accidentally embed private plots) - - The thumbnail image appears on: https://plot.ly/javascript/ - -## Search - -We now have search via algolia implemented on our index and reference documentation pages! Please refer to our [make README](https://github.com/plotly/documentation/blob/source-design-merge/make_instructions.txt) for more information on how search works and instructions on how to update or edit Plotly search indices. + + - Create a feature branch and use `git status` to list changed files. + ``` + git checkout -b your_feature_branch + git status + ``` + - Add, commit, and push the files that you'd like to add to your PR: + ``` + git add file-a + git add file-b + git commit -m 'message about your changes' + git push origin your_feature_branch + ``` + - Visit the [documentation repo](https://github.com/plotly/documentation) and open a pull request against the `source-design-merge` branch. You can then tag **@jdamiba** for a review. + +## Style Edits + +Please refer to our [Styles README](https://github.com/plotly/documentation/blob/source-design-merge/style_README.md) Thanks for contributing to our documentation!! From 7bd0d57663fa90cfed97b292abd64d276ff18fd0 Mon Sep 17 00:00:00 2001 From: Joseph Damiba Date: Tue, 7 Jan 2020 19:55:07 -0500 Subject: [PATCH 2/6] typo fixup --- Contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contributing.md b/Contributing.md index 71fe38d379bf..13d3afa0a330 100755 --- a/Contributing.md +++ b/Contributing.md @@ -16,7 +16,7 @@ For information about editing **plotly.js** documentation [click here](https://g The content for Plotly's Python graphing library documentation (hosted at https://plot.ly/python) **IS NOT** contained in this repository. It is contained in the `plotly.py` repository at https://github.com/plotly/plotly.py/tree/master/doc and is cloned into this repository at build time. -For information about editing **plotly.py** documentation [click here] (https://github.com/plotly/plotly.py/blob/master/doc/README.md). +For information about editing **plotly.py** documentation [click here](https://github.com/plotly/plotly.py/blob/master/doc/README.md). ### plotly.r From 570598af45ac138427b70b2c5c78c533721c2249 Mon Sep 17 00:00:00 2001 From: Joseph Damiba Date: Tue, 7 Jan 2020 19:56:56 -0500 Subject: [PATCH 3/6] typo fixup --- Contributing.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Contributing.md b/Contributing.md index 13d3afa0a330..d0e12e3d4a9b 100755 --- a/Contributing.md +++ b/Contributing.md @@ -76,13 +76,11 @@ bundle install Note these dependencies should be the same version that [gh-pages](https://pages.github.com/versions/) is using. -5. When Plotly deploys its graphing libraries documentation to GitHub pages, a function is run to simultaneously update the graphing libraries plot schema in order to keep the two in sync. To do this successfully you have to make sure you have Python and the `requests` Python package installed in your local development environment: `pip install requests`. +5. Serve the Jekyll application: `bundle exec jekyll serve --config _config_dev.yml`. +6. Visit the pages at: [http://localhost:4000/](http://localhost:4000) +7. When you make changes, Jekyll should automatically regenerate the application for you. Read the messages in your terminal to check it out. -6. Serve the Jekyll application: `bundle exec jekyll serve --config _config_dev.yml`. -7. Visit the pages at: [http://localhost:4000/](http://localhost:4000) -8. When you make changes, Jekyll should automatically regenerate the application for you. Read the messages in your terminal to check it out. - -There are a TON of posts in here, so rendering can take up to thirty minutes! You can *limit* the number of posts that render by [excluding folders](https://jekyllrb.com/docs/configuration/options/) from being served using custom Jekyll configuration options. +You can limit the number of posts that render by [excluding folders](https://jekyllrb.com/docs/configuration/options/) from being served using custom Jekyll configuration options. To do so, create a `_config_personal.yml` file: From 7442da97920ba5317003016927d90b276f4d6f10 Mon Sep 17 00:00:00 2001 From: Joseph Damiba Date: Wed, 8 Jan 2020 01:51:15 -0500 Subject: [PATCH 4/6] edits --- Contributing.md | 80 ++++++++++++++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 31 deletions(-) diff --git a/Contributing.md b/Contributing.md index d0e12e3d4a9b..80bb388dd3f2 100755 --- a/Contributing.md +++ b/Contributing.md @@ -1,40 +1,33 @@ # Contributing to Plotly's Graphing Libraries Documentation -Plotly welcomes contributions to its [open-source graphing libraries documentation](https://plot.ly/graphing-libraries) from its community of users. - -The `source-design-merge` branch of this repository hosts a Jekyll application hosted on GitHub Pages that serves Plotly's graphing libraries documentation. - -The index page for the documentation website is located at https://plot.ly/graphing-libraries. - -### plotly.js - -Please be aware that **only the content of Plotly's JavaScript graphing library documentation** (hosted at https://plot.ly/javascript) is contained in this repository. You can find the content in the `_posts/plotly_js` directory. +## Repo Overview -For information about editing **plotly.js** documentation [click here](https://github.com/plotly/documentation/blob/readme-updates/_posts/plotly_js/README.md). - -### plotly.py - -The content for Plotly's Python graphing library documentation (hosted at https://plot.ly/python) **IS NOT** contained in this repository. It is contained in the `plotly.py` repository at https://github.com/plotly/plotly.py/tree/master/doc and is cloned into this repository at build time. +Plotly welcomes contributions to its [open-source graphing libraries documentation](https://plot.ly/graphing-libraries) from its community of users. -For information about editing **plotly.py** documentation [click here](https://github.com/plotly/plotly.py/blob/master/doc/README.md). +This repository mainly serves: +- Plotly's graphing libraries documentation index page at https://plot.ly/graphing-libraries. -### plotly.r +- Plotly's JavaScript graphing library documentation at https://plot.ly/javascript + - Please be aware that **only the content of Plotly's JavaScript graphing library documentation** (hosted at https://plot.ly/javascript) is contained in this repository. You can find the content in the `_posts/plotly_js` directory. + - For information about editing **plotly.js** documentation [click here](https://github.com/plotly/documentation/blob/readme-updates/_posts/plotly_js/README.md). -The content for Plotly's R graphing library documentation (hosted at https://plot.ly/r) **IS NOT** contained in this repository. It is contained in the `plotly.r-docs` repository at https://github.com/plotly/plotly.r-docs/ and is cloned into this repository at build time. +- Plotly's Python graphing library documentation at https://plot.ly/python + - The content for Plotly's Python graphing library documentation (hosted at https://plot.ly/python) **IS NOT** contained in this repository. It is contained in the `plotly.py` repository at https://github.com/plotly/plotly.py/tree/master/doc and is cloned into this repository at build time. + - For information about editing **plotly.py** documentation [click here](https://github.com/plotly/plotly.py/blob/master/doc/README.md). -For information about editing Plotly's **R** documentation [click here](https://github.com/plotly/plotly.r-docs/blob/master/README.md). +- Plotly's R graphing library documentation at https://plot.ly/r + - The content for Plotly's R graphing library documentation (hosted at https://plot.ly/r) **IS NOT** contained in this repository. It is contained in the `plotly.r-docs` repository at https://github.com/plotly/plotly.r-docs/ and is cloned into this repository at build time. + - For information about editing Plotly's **R** documentation [click here](https://github.com/plotly/plotly.r-docs/blob/master/README.md). -**For more information about the build process, inspect the CircleCI configuration file in this repository at https://github.com/plotly/documentation/blob/source-design-merge/.circleci/config.yml.** - ## Contribute Quickly to Plotly's JavaScript Graphing Library Documentation -To quickly make a contribution to Plotly's JavaScript graphing libraries documentation, simply submit a pull request with the change you would like to suggest to the `source-design-merge` branch of this repository. +To quickly make a contribution to Plotly's JavaScript graphing libraries documentation, simply submit a pull request with the change you would like to suggest. The easiest way to do this is to follow the `Edit this page on GitHub` link at the top right of the page you are interested in contributing to: ![Screen Shot 2020-01-07 at 12 45 39 PM](https://user-images.githubusercontent.com/1557650/71916356-bfe53800-314b-11ea-92b6-eb763037f6d5.png) -**You don't have to worry about breaking the site when you submit a pull request!** This is because your change will not be merged to production immediately. A Plotly team member will first perform a code review on your pull request. +**Note:** You don't have to worry about breaking the site when you submit a pull request!** This is because your change will not be merged to production immediately. A Plotly team member will first perform a code review on your pull request. ## How To Get The Application Working Locally @@ -52,6 +45,8 @@ git fetch origin git checkout source-design-merge ``` +**Note:** For historical reasons, the `source-design-merge` branch is the `master` branch of this repository. + Running `git status` in your terminal should then output the following: ```sh @@ -63,7 +58,7 @@ nothing to commit, working tree clean 2. Download Ruby and check your `Ruby` version by running the `ruby --version` command in your terminal. -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. +**Note:** 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. 3. Download Jekyll and check your Jekyll version by running the `jekyll -v` command in your terminal. We recommend using the same ruby version as [gh-pages](https://pages.github.com/versions/). @@ -74,28 +69,51 @@ gem install bundler bundle install ``` -Note these dependencies should be the same version that [gh-pages](https://pages.github.com/versions/) is using. +**Note:** These dependencies should be the same version that [gh-pages](https://pages.github.com/versions/) is using. 5. Serve the Jekyll application: `bundle exec jekyll serve --config _config_dev.yml`. + 6. Visit the pages at: [http://localhost:4000/](http://localhost:4000) -7. When you make changes, Jekyll should automatically regenerate the application for you. Read the messages in your terminal to check it out. -You can limit the number of posts that render by [excluding folders](https://jekyllrb.com/docs/configuration/options/) from being served using custom Jekyll configuration options. +**Note** The default Jekyll configuration file only builds the JavaScript posts by [excluding folders](https://jekyllrb.com/docs/configuration/options/). If you want to override this behavior, serve the application with a custom Jekyll configuration file in the root of the repository. Do this by copying `_config_dev.yml`, renaming it `_config_personal.yml`, and modifying the `exclude` statement. -To do so, create a `_config_personal.yml` file: +- If you name the Jekyll configuration file `_config_personal.yml`, it will be caught by the `.gitignore` file and not committed to version control. +- Run `bundle exec jekyll serve --config _config_personal.yml` to use the custom configuration file +- Example configuration: ```yml -staticurl: http://localhost:4000/all_static -exclude: [_posts/ggplot2, _posts/julia, _posts/matlab, _posts/matplotlib, _posts/nodejs, _posts/r, posts/python] # [_posts/plotly_js,] +# --- +# Excludes every directory except JavaScript +# --- +exclude: ['_posts/reference_pages', _posts/ggplot2','_posts/julia','_posts/matlab','_posts/node_js','_posts/r','_posts/python','_posts/python-v3','_posts/misc','_posts/dashboards',_posts/scala', '_posts/nodejs', 'node_modules'] ``` -and you'll only load the files in `_posts/plotly_js`. +and you'll only load the files in `_posts/plotly_js` directory because that is the only directory that is not excluded. Change it to this: ```yml +# --- +# Excludes no directory +# --- staticurl: http://localhost:4000/all_static exclude: [] ``` -and it'll load everything. \ No newline at end of file +and you'll load every file because no directories are excluded. + +## Continuous Integration + +Whenever a pull request is made, a continuous integration workflow is initiated. This includes of: + - running the `check-or-enforce-order.py` and `front-matter-ci.py` scripts inside of a Docker container to validate YAML front-matter + - Percy screenshot testing + +Making sure that a pull request passes every continuous integration test is a part of the code review process. + +**For more information about the build process, inspect the CircleCI configuration file in this repository at https://github.com/plotly/documentation/blob/source-design-merge/.circleci/config.yml.** + +## Other Documentation + +This repository also contains: + - Plotly's Node.js, Matlab, Scala, Julia, and Python V3 graphing libraries documentation + - the reference pages for Plotly's JavaScript, Python, R, and Matlab graphing libraries. From d133725134260b1a65c6d2c5cd780ca7b3dfce27 Mon Sep 17 00:00:00 2001 From: Joseph Damiba Date: Thu, 9 Jan 2020 15:05:39 -0500 Subject: [PATCH 5/6] change URL --- Contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contributing.md b/Contributing.md index 80bb388dd3f2..81d0197e30d0 100755 --- a/Contributing.md +++ b/Contributing.md @@ -9,7 +9,7 @@ This repository mainly serves: - Plotly's JavaScript graphing library documentation at https://plot.ly/javascript - Please be aware that **only the content of Plotly's JavaScript graphing library documentation** (hosted at https://plot.ly/javascript) is contained in this repository. You can find the content in the `_posts/plotly_js` directory. - - For information about editing **plotly.js** documentation [click here](https://github.com/plotly/documentation/blob/readme-updates/_posts/plotly_js/README.md). + - For information about editing **plotly.js** documentation [click here](https://github.com/plotly/documentation/blob/source-design-merge/_posts/plotly_js/README.md). - Plotly's Python graphing library documentation at https://plot.ly/python - The content for Plotly's Python graphing library documentation (hosted at https://plot.ly/python) **IS NOT** contained in this repository. It is contained in the `plotly.py` repository at https://github.com/plotly/plotly.py/tree/master/doc and is cloned into this repository at build time. From bb914575001fd6c6662683e3b249f49b4e9b01ad Mon Sep 17 00:00:00 2001 From: Joseph Damiba Date: Thu, 9 Jan 2020 15:06:05 -0500 Subject: [PATCH 6/6] change URL --- _posts/plotly_js/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_posts/plotly_js/README.md b/_posts/plotly_js/README.md index 07385f5a05c1..6bf9c4061289 100644 --- a/_posts/plotly_js/README.md +++ b/_posts/plotly_js/README.md @@ -18,7 +18,7 @@ The easiest way to do this is to follow the `Edit this page on GitHub` link at t For contributions such as new example posts, we recommend setting up a local development environment so that you can test your changes as you work on them. -**See the `How To Get The Application Working Locally` section of the [Contributing Guide](https://github.com/plotly/documentation/blob/readme-updates/Contributing.md) to learn how to clone this repository to your local development environment and install its dependencies.** +**See the `How To Get The Application Working Locally` section of the [Contributing Guide](https://github.com/plotly/documentation/blob/source-design-merge/Contributing.md) to learn how to clone this repository to your local development environment and install its dependencies.** Then follow these instructions to create or modify a new post. If the post is the first of its chart type, you need to create an index page for it first.