You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+49-29Lines changed: 49 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,13 +34,13 @@ The easiest way to do this is to follow the `Edit this page on GitHub` link at t
34
34
35
35
36
36
37
-
**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.
37
+
**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.
38
38
39
39
## How To Get The Application Working Locally
40
40
41
-
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.
41
+
For more extensive changes to Plotly'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.
42
42
43
-
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/).
43
+
This involves cloning the repository and installing its dependencies: [Git](https://git-scm.com/), [Ruby](https://www.ruby-lang.org/en/), and the Python packages used by the CI scripts.
44
44
45
45
1. Use [`git`](https://git-scm.com/) to [clone](https://git-scm.com/docs/git-clone) the public `plotly/graphing-library-docs` repository.
46
46
@@ -60,42 +60,41 @@ Your branch is up to date with 'origin/master'.
60
60
nothing to commit, working tree clean
61
61
```
62
62
63
-
2.Download Ruby and check your `Ruby`version by running the `ruby --version` command in your terminal.
63
+
2.Install Ruby 2.7.4. Check your version with `ruby --version`. [RVM](https://rvm.io/rvm/install) is helpful for installing and managing Ruby versions.
64
64
65
-
**Note:** We recommend using `version 2.7.4`, 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.
65
+
3. Install all remaining dependencies (Ruby gems, Python packages, Node packages, and upstream tutorial content) in one step:
66
66
67
-
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/).
67
+
```sh
68
+
make setup
69
+
```
68
70
69
-
4. Install bundler and dependencies from the Jekyll applicaton's [`Gemfile`](https://github.com/plotly/graphing-library-docs/blob/master/Gemfile) by running the following commands in your terminal:
71
+
If you'd rather install each piece manually, run these instead:
5.Serve the Jekyll application: `bundle exec jekyll serve --config _config_dev.yml`.
82
+
5.Visit the pages at: [http://localhost:4000/](http://localhost:4000)
79
83
80
-
6. Visit the pages at: [http://localhost:4000/](http://localhost:4000)
81
-
82
-
**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.
84
+
**Note** The default development configuration (`_config_dev.yml`) excludes `_posts/plotly_js` and `_posts/python-v3` for faster builds. If you want to include or exclude different folders, copy `_config_dev.yml`, rename it `_config_personal.yml`, and modify the `exclude` statement.
83
85
84
86
- If you name the Jekyll configuration file `_config_personal.yml`, it will be caught by the `.gitignore` file and not committed to version control.
85
87
- Run `bundle exec jekyll serve --config _config_personal.yml` to use the custom configuration file
86
88
87
-
- Example configuration:
89
+
- Example configuration that loads **only** the JavaScript posts:
and you'll load every file because no directories are excluded.
106
+
**Note** The Python, R, Julia, Matlab, C#, and F# tutorial content is not stored in this repository — it is cloned in at build time from upstream repos by `make fetch_upstream_files`. If you want those pages to render locally, run `make fetch_upstream_files` before serving.
108
107
109
108
## Continuous Integration
110
109
111
-
Whenever a pull request is made, a continuous integration workflow is initiated. This includes of:
112
-
- running the `check-or-enforce-order.py` and `front-matter-ci.py` scripts inside of a Docker container to validate YAML front-matter
113
-
- Percy screenshot testing
110
+
Whenever a pull request is made, the GitHub Actions workflow defined in [`.github/workflows/build.yml`](https://github.com/plotly/graphing-library-docs/blob/master/.github/workflows/build.yml) runs. It:
111
+
- runs `front-matter-ci.py` to validate YAML front-matter
112
+
- runs `check-or-enforce-order.py` against each tutorial directory to validate the `order` field
113
+
- builds the site with `bundle exec jekyll build`
114
+
- captures Percy snapshots for visual regression review
115
+
116
+
Making sure that a pull request passes every CI check is part of the code review process.
117
+
118
+
## Search indices
114
119
115
-
Making sure that a pull request passes every continuous integration test is a part of the code review process.
120
+
Search on plotly.com docs pages is powered by Algolia indices that are updated separately from the site build. There are four indices, each updated by its own `make` target:
116
121
117
-
**For more information about the build process, inspect the CircleCI configuration file in this repository at https://github.com/plotly/graphing-library-docs/blob/master/.circleci/config.yml.**
You can browse the indices at https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/.
130
+
131
+
**When to update:** Run the appropriate `update_*_search` target whenever a new tutorial is added to the corresponding `_posts/` directory. The `schema` index should be updated when a new plotly.js version is released.
132
+
133
+
**How to exclude files from an index:** Each search index has its own Jekyll config (`_config_python_search.yml`, `_config_r_search.yml`, etc.) with an `algolia.excluded_files` list. Add files or paths there to keep them out of search results.
134
+
135
+
**Algolia API key:** Updating the indices requires a private Algolia API key set as an environment variable. Request it from a Plotly maintainer via an issue on this repository.
136
+
137
+
Run `make help` to see all available `make` targets, including search-index and upstream-fetch commands.
- the reference pages for Plotly's JavaScript, Python, R, and Matlab graphing libraries.
124
-
142
+
- Plotly's Node.js, Scala, and Python V3 graphing libraries documentation
143
+
- the reference pages for Plotly's JavaScript, Python, R, and Matlab graphing libraries
144
+
- landing/index pages for the Python, R, ggplot2, Julia, Matlab, C#, and F# docs (the tutorial content for those languages is fetched from upstream repos at build time)
1. 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
+
The Julia tutorial content displayed on https://plotly.com/julia/ is **not** authored in this repository. It lives in [plotly/plotlyjs.jl-docs](https://github.com/plotly/plotlyjs.jl-docs) and is fetched into this repo at build time by `make fetch_upstream_files`.
10
4
11
-
2. Install bundler and a couple dependencies from the gemfile:
5
+
## Where to make changes
12
6
13
-
```
14
-
$ gem install bundler
15
-
$ bundle install
7
+
-**Tutorial content (chart examples, prose, etc.):** edit the source files in [plotly/plotlyjs.jl-docs](https://github.com/plotly/plotlyjs.jl-docs). See that repo's README for authoring instructions.
8
+
-**The Julia landing/index pages** that appear on https://plotly.com/julia/ (sidebar, categories, etc.): edit the corresponding files in this repository under `_posts/julia/` and the include files under `_includes/`.
16
9
17
-
```
18
-
<b>IMPORTANT</b> -If not using bundler and the gemfile, [install the same jekyll version that GitHub Pages is using](https://pages.github.com/versions/).
10
+
## Building locally
19
11
20
-
## Create Julia Documentation:
21
-
Our Julia tutorials are written in HTML files with embedded plot examples.
22
-
##### In `documentation/_posts/julia`
23
-
1. Create a folder titled with the chart type or topic you're adding to the documentation (i.e. `bar`)
24
-
2.`cd` into the folder you created and create an html index file labeled: `yyyy-mm-dd-chart_type_julia_index.html`. Copy the index file template below and replace with the necessary information pertaining to the doc you are creating.
25
-
```
26
-
---
27
-
title: Julia Add-Chart-Type-or-Topic | Examples | Plotly
28
-
name: Add-Chart-Type-or-Topic
29
-
permalink: julia/add-chart-type-or-topic/
30
-
description: How to make a add-chart-type-or-topic in Julia. Add an additional sentence summarizing chart-type or topic.
31
-
layout: base
32
-
thumbnail: thumbnail/add-chart-type-or-topic.jpg *MORE INFO ON ADDING THUMBNAILS BELOW
- See additional options [HERE](https://github.com/plotly/graphing-library-docs/blob/master/_includes/documentation_eg.html#L1)
49
-
-***`order` defines the order in which the tutorials appear in each section on plot.ly/julia. Please take a look at https://plotly.com/julia/ and order your tutorial next to similar chart types. <b>Note</b> `order` can be a float.
12
+
To preview Julia documentation locally, follow the setup steps in the main [README.md](https://github.com/plotly/graphing-library-docs/blob/master/README.md#how-to-get-the-application-working-locally), then run:
50
13
51
-
3. Create an example and save it on https://plotly.com/.
14
+
```sh
15
+
make fetch_upstream_files
16
+
bundle exec jekyll serve --config _config_dev.yml
17
+
```
52
18
53
-
4. Add an HTML file (`yyyy-mm-dd-example-name.html`) for each example. The HTML file should have a header (template below), followed by the Julia code used to create the example.
54
-
```
55
-
---
56
-
name: Basic Bar Chart **
57
-
plot_url: https://plotly.com/~PlotBot/39
58
-
language: julia
59
-
suite: bar
60
-
order: 1 **
61
-
sitemap: false
62
-
arrangement: horizontal
63
-
---
64
-
# Learn about API authentication here: https://plotly.com/julia/getting-started
65
-
# Find your api_key here: https://plotly.com/settings/api
19
+
`fetch_upstream_files` clones the latest built Julia content into `_posts/julia/html/`. Without it, the Julia pages will not render locally.
- <b>Now we have an awesome navigation bar on the left side of our tutorial pages.</b> 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`
83
-
-`order` examples from basic -> advanced.
84
-
- 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 :) )
85
-
86
-
8. Add Thumbnail Images
87
-
- Thumbnail images should named `your-tutorial-chart.jpg` and be *EXACTLY* 160px X 160px
88
-
- Thumbnail images should be clear and interesting. You do not need to capture the ENTIRE chart, but rather focus on the most interesting part of the chart.
- From the <b>Amazon Web Services Console</b> select <b>S3 (Scalable Storage in the Cloud)</b> then select <b>plotly-tutorials</b> -> <b>plotly-documentation</b> -> <b>thumbnail</b>
93
-
- Now from <b>All Buckets /plotly-tutorials/plotly-documentation/thumbnail</b> select the <b>Actions</b> dropdown and <b>upload</b> your .jpg file
94
-
95
-
##### In the terminal in the `documentation` repo
96
-
9. Commit and Push your tutorial
97
-
-`git add` your .html files
98
-
-`git commit -m "include a message about the tutorial you're adding"`
99
-
-`git push origin master`
100
-
101
-
10. To proof your work, serve the pages locally by running: `bundle exec jekyll serve --config _config_dev.yml` from the root of the documentation repo.
102
-
For more information see these steps: https://github.com/plotly/graphing-library-docs/blob/master/Contributing.md
103
-
104
-
11. Deploy changes by running `bundle exec rake deploy` from the root of the documentation repo.
105
-
106
-
##### At https://plotly.com/julia
107
-
12. Check your Tutorial!!!! This is a <b>very important</b> step.
108
-
<b>PLEASE</b> visit https://plotly.com/julia/your-tutorial and make sure everything looks correct :)
109
-
110
-
- Some common problems that you should check for:
111
-
- 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)
112
-
- The thumbnail image appears on: https://plotly.com/julia/
113
-
114
-
Thanks for contributing to our documentation!!
23
+
Open a pull request against the `master` branch of [plotly/graphing-library-docs](https://github.com/plotly/graphing-library-docs) for changes to the Julia landing pages, or against [plotly/plotlyjs.jl-docs](https://github.com/plotly/plotlyjs.jl-docs) for changes to tutorial content. A Plotly maintainer will review.
Copy file name to clipboardExpand all lines: _posts/plotly_js/README.md
+5-8Lines changed: 5 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,7 +18,7 @@ The easiest way to do this is to follow the `Edit this page on GitHub` link at t
18
18
19
19
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.
20
20
21
-
**See the `How To Get The Application Working Locally` section of the [Contributing Guide](https://github.com/plotly/graphing-library-docs/blob/master/Contributing.md) to learn how to clone this repository to your local development environment and install its dependencies.**
21
+
**See the `How To Get The Application Working Locally` section of the [Contributing Guide](https://github.com/plotly/graphing-library-docs/blob/master/README.md#how-to-get-the-application-working-locally) to learn how to clone this repository to your local development environment and install its dependencies.**
22
22
23
23
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.
{% include posts/auto_examples.html examples=examples %}
46
46
```
47
-
- Make sure to update `_includes/posts/documentation_eg.html`, `_includes/layouts/side-bar.html`, and `_data/display_as_py_r_js.yml`and the CI python scripts with the new chart type!
47
+
- Make sure to update `_includes/posts/documentation_eg.html`, `_includes/layouts/side-bar.html`, and `_data/display_as_py_r_js.yml`with the new chart type. If the chart type needs to be tracked for front-matter or ordering validation, also update `front-matter-ci.py` and `check-or-enforce-order.py`.
48
48
49
49
- Index pages for chart categories must have `order: 5`.
- 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.
111
-
- Use images.plot.ly for adding new images. The password is in the Plotly 1Password Engineering Vault.
- From the <b>Amazon Web Services Console</b> select <b>S3 (Scalable Storage in the Cloud)</b> then select <b>plotly-tutorials</b> -> <b>plotly-documentation</b> -> <b>thumbnail</b>
114
-
- Now from <b>All Buckets /plotly-tutorials/plotly-documentation/thumbnail</b> select the <b>Actions</b> dropdown and <b>upload</b> your .jpg file
111
+
- Plotly hosts thumbnail images on `images.plot.ly`. If you do not have upload access, attach the image to your pull request and a maintainer will upload it on your behalf.
- Visit the [documentation repo](https://github.com/plotly/graphing-library-docs) and open a pull request!. You can then tag **@jdamiba** for a review.
142
+
- Visit the [documentation repo](https://github.com/plotly/graphing-library-docs) and open a pull request. A Plotly maintainer will review it.
0 commit comments