diff --git a/Contributing.md b/Contributing.md index 0d5ca9bf62b5..81d0197e30d0 100755 --- a/Contributing.md +++ b/Contributing.md @@ -1,10 +1,43 @@ -# 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. +## Repo Overview -## Clone the Repo and Install Dependencies +Plotly welcomes contributions to its [open-source graphing libraries documentation](https://plot.ly/graphing-libraries) from its community of users. -1. Clone the repo and then check out the source-design-merge branch: +This repository mainly serves: +- Plotly's graphing libraries documentation index page at https://plot.ly/graphing-libraries. + +- 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/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. + - For information about editing **plotly.py** documentation [click here](https://github.com/plotly/plotly.py/blob/master/doc/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). + +## 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. + +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) + +**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 + +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 +45,75 @@ 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. +**Note:** For historical reasons, the `source-design-merge` branch is the `master` branch of this repository. -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` +**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. -## 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. Serve the Jekyll application: `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 +6. Visit the pages at: [http://localhost:4000/](http://localhost:4000) -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. +**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. -For example, change `_config_dev.yml` to this: +- 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,] +# --- +# 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/python`. +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 +Change it to this: ```yml +# --- +# Excludes no directory +# --- 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. +and you'll load every file because no directories are excluded. -(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. +## Continuous Integration -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. +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 -## Search +Making sure that a pull request passes every continuous integration test is a part of the code review process. -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. +**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.** -## Style Edits +## Other Documentation -Please refer to our [Styles README](https://github.com/plotly/documentation/blob/source-design-merge/style_README.md) +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. diff --git a/_posts/plotly_js/README.md b/_posts/plotly_js/README.md index b8329eb53e78..6bf9c4061289 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/source-design-merge/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!!