diff --git a/README.md b/README.md
index 475dd6804..d32751900 100755
--- a/README.md
+++ b/README.md
@@ -30,17 +30,17 @@ This repository mainly serves:
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:
+The easiest way to do this is to follow the `Suggest an edit to this page` link at the top right of the page you are interested in contributing to:
-
+
-**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.
+**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.
+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.
-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/).
+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.
1. Use [`git`](https://git-scm.com/) to [clone](https://git-scm.com/docs/git-clone) the public `plotly/graphing-library-docs` repository.
@@ -60,42 +60,41 @@ Your branch is up to date with 'origin/master'.
nothing to commit, working tree clean
```
-2. Download Ruby and check your `Ruby` version by running the `ruby --version` command in your terminal.
+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.
-**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.
+3. Install all remaining dependencies (Ruby gems, Python packages, Node packages, and upstream tutorial content) in one step:
-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/).
+```sh
+make setup
+```
-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:
+If you'd rather install each piece manually, run these instead:
```sh
-gem install bundler
-bundle install
+gem install bundler && bundle install # Ruby gems (installs Jekyll)
+pip install -r requirements.txt # Python packages
+npm install # Node packages (for the gulp/scss workflow)
+make fetch_upstream_files # Python, R, Julia, Matlab, C#, and F# tutorial content
```
-**Note:** These dependencies should be the same version that [gh-pages](https://pages.github.com/versions/) is using.
+4. Serve the Jekyll application: `bundle exec jekyll serve --config _config_dev.yml`.
-5. Serve the Jekyll application: `bundle exec jekyll serve --config _config_dev.yml`.
+5. Visit the pages at: [http://localhost:4000/](http://localhost:4000)
-6. Visit the pages at: [http://localhost:4000/](http://localhost:4000)
-
-**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.
+**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.
- 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:
+- Example configuration that loads **only** the JavaScript posts:
```yml
# ---
# 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']
+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` directory because that is the only directory that is not excluded.
-
-Change it to this:
-
+- Example configuration that loads **every** directory:
```yml
# ---
# Excludes no directory
@@ -104,21 +103,42 @@ staticurl: http://localhost:4000/all_static
exclude: []
```
-and you'll load every file because no directories are excluded.
+**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.
## 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
+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:
+- runs `front-matter-ci.py` to validate YAML front-matter
+- runs `check-or-enforce-order.py` against each tutorial directory to validate the `order` field
+- builds the site with `bundle exec jekyll build`
+- captures Percy snapshots for visual regression review
+
+Making sure that a pull request passes every CI check is part of the code review process.
+
+## Search indexes
-Making sure that a pull request passes every continuous integration test is a part of the code review process.
+Search on plotly.com docs pages is powered by Algolia indexes that are updated separately from the site build. There are four indexes, each updated by its own `make` target:
-**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.**
+| Index | Search on | Update with |
+| --- | --- | --- |
+| `js_docs` | https://plotly.com/javascript/ | `make update_js_search` |
+| `python_docs` | https://plotly.com/python/, https://plotly.com/pandas/ | `make update_python_search` |
+| `r_docs` | https://plotly.com/r/, https://plotly.com/ggplot2/ | `make update_r_search` |
+| `schema` | reference pages (e.g. https://plotly.com/python/reference) | `make update_ref_search` |
+
+You can browse the indexes at https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/.
+
+**When to update:** Run the appropriate `update_*_search` target whenever a new tutorial is added to the corresponding `_posts/` directory. Run the `schema` index update command when a new plotly.js version is released.
+
+**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.
+
+**Algolia API key:** Updating the indexes requires a private Algolia API key set as an environment variable. Request it from a Plotly maintainer via an issue on this repository.
+
+Run `make help` to see all available `make` targets, including search-index and upstream-fetch commands.
## 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.
-
+- Plotly's Node.js, Scala, and Python V3 graphing libraries documentation
+- the reference pages for Plotly's JavaScript, Python, R, and Matlab graphing libraries
+- 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)
diff --git a/_posts/julia/README.md b/_posts/julia/README.md
index 4c0e70a48..179c43593 100644
--- a/_posts/julia/README.md
+++ b/_posts/julia/README.md
@@ -1,114 +1,23 @@
# Contribute to Plotly's [Julia Documentation](https://plotly.com/julia/)
-## Initial Steps:
-0. Clone the repo.:
- ```
- $ git clone git@github.com:plotly/graphing-library-docs.git
- $ cd graphing-library-docs
- ```
-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.
+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`.
-2. Install bundler and a couple dependencies from the gemfile:
+## Where to make changes
- ```
- $ gem install bundler
- $ bundle install
+- **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.
+- **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/`.
- ```
-IMPORTANT -If not using bundler and the gemfile, [install the same jekyll version that GitHub Pages is using](https://pages.github.com/versions/).
+## Building locally
-## Create Julia Documentation:
-Our Julia tutorials are written in HTML files with embedded plot examples.
-##### In `documentation/_posts/julia`
-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_julia_index.html`. Copy the index file template below and replace with the necessary information pertaining to the doc you are creating.
- ```
- ---
- title: Julia Add-Chart-Type-or-Topic | Examples | Plotly
- name: Add-Chart-Type-or-Topic
- permalink: julia/add-chart-type-or-topic/
- description: How to make a add-chart-type-or-topic in Julia. 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: julia
- page_type: example_index
- display_as: **SEE BELOW
- order: ***SEE BELOW
- ---
- {% assign examples = site.posts | where:"language","julia" | 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://plotly.com/julia/#basic-charts
- - 'statistical' = https://plotly.com/julia/#statistical-charts
- - 'scientific' = https://plotly.com/julia/#scientific-charts
- - 'financial' = https://plotly.com/julia/#financial-charts
- - 'maps' = https://plotly.com/julia/#maps
- - '3d_charts' = https://plotly.com/julia/#3d-charts
- - See additional options [HERE](https://github.com/plotly/graphing-library-docs/blob/master/_includes/documentation_eg.html#L1)
- - *** `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. Note `order` can be a float.
+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:
-3. Create an example and save it on https://plotly.com/.
+```sh
+make fetch_upstream_files
+bundle exec jekyll serve --config _config_dev.yml
+```
-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.
- ```
- ---
- name: Basic Bar Chart **
- plot_url: https://plotly.com/~PlotBot/39
- language: julia
- suite: bar
- order: 1 **
- sitemap: false
- arrangement: horizontal
- ---
- # Learn about API authentication here: https://plotly.com/julia/getting-started
- # Find your api_key here: https://plotly.com/settings/api
+`fetch_upstream_files` clones the latest built Julia content into `_posts/julia/html/`. Without it, the Julia pages will not render locally.
- using Plotly
+## Pull requests
-
- data = [
- [
- "x" => ["giraffes", "orangutans", "monkeys"],
- "y" => [20, 14, 23],
- "type" => "bar"
- ]
- ]
- response = Plotly.plot(data, ["filename" => "basic-bar", "fileopt" => "overwrite"])
- plot_url = response["url"]
- ```
-
-6. Best Practices:
- - 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. Commit and Push your tutorial
- - `git add` your .html files
- - `git commit -m "include a message about the tutorial you're adding"`
- - `git push origin master`
-
-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.
-For more information see these steps: https://github.com/plotly/graphing-library-docs/blob/master/Contributing.md
-
-11. Deploy changes by running `bundle exec rake deploy` from the root of the documentation repo.
-
-##### At https://plotly.com/julia
-12. Check your Tutorial!!!! This is a very important step.
- PLEASE visit https://plotly.com/julia/your-tutorial and make sure everything looks correct :)
-
- - 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://plotly.com/julia/
-
-Thanks for contributing to our documentation!!
+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.
diff --git a/_posts/plotly_js/README.md b/_posts/plotly_js/README.md
index ebcf4e942..82a5b5a00 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/graphing-library-docs/blob/master/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/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.**
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.
@@ -44,7 +44,7 @@ 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 %}
```
- - 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!
+ - 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`.
- Index pages for chart categories must have `order: 5`.
@@ -76,7 +76,7 @@ var data = [
x: ['giraffes', 'orangutans', 'monkeys'],
y: [20, 14, 23],
type: 'bar'
- }The
+ }
];
Plotly.newPlot('myDiv', data);
@@ -108,10 +108,7 @@ Plotly.newPlot('myDiv', data);
- 'maps' = https://plotly.com/javascript/maps
- '3d_charts' = https://plotly.com/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
+ - 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.
## Modify An Existing Post:
@@ -142,7 +139,7 @@ Plotly.newPlot('myDiv', data);
git commit -m 'message about your changes'
git push origin your_feature_branch
```
- - Visit the [documentation repo](https://github.com/plotly/graphing-library-docs) and open a pull request!. You can then tag **@jdamiba** for a review.
+ - Visit the [documentation repo](https://github.com/plotly/graphing-library-docs) and open a pull request. A Plotly maintainer will review it.
## Style Edits
diff --git a/_posts/r/README.md b/_posts/r/README.md
index 9044ee1e2..c2d5de53d 100644
--- a/_posts/r/README.md
+++ b/_posts/r/README.md
@@ -1,123 +1,27 @@
# Contribute to Plotly's [R Documentation](https://plotly.com/r/)
-These are the instructions for contributing to the subset of the documentation for Plotly's R graphing library which deals with Chart Studio.
+The R tutorial content displayed on https://plotly.com/r/ and https://plotly.com/ggplot2/ is **not** authored in this repository. It lives in [plotly/plotly.r-docs](https://github.com/plotly/plotly.r-docs) and is fetched into this repo at build time by `make fetch_upstream_files`.
-In order to contribute to the majority of Plotly's R graphing library documentation (which is not related to Chart Studio), please visit the [plotly.r-docs](https://github.com/plotly/plotly.r-docs) repository.
+## Where to make changes
-## Initial Steps:
-1. Clone the repo:
+- **Tutorial content (Rmd files, chart examples, prose):** edit the source files in [plotly/plotly.r-docs](https://github.com/plotly/plotly.r-docs). See that repo's README for authoring instructions.
+- **The R landing/index pages** that appear on https://plotly.com/r/ (sidebar, categories, etc.) — for example `2015-07-30-r-index.md` and the various `*-index.md` files in this directory: edit those files directly in this repository under `_posts/r/`.
- ```
- $ git clone git@github.com:plotly/graphing-library-docs.git
- $ cd graphing-library-docs
- ```
+## Building locally
-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.
+To preview R 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:
-3. Install bundler and a couple dependencies from the gemfile:
+```sh
+make fetch_upstream_files
+bundle exec jekyll serve --config _config_dev.yml
+```
- ```
- $ gem install bundler
- $ bundle install
+`fetch_upstream_files` clones the latest built R and ggplot2 content into `_posts/r/md/` and `_posts/ggplot2/md/`. Without it, the R tutorial pages will not render locally.
- ```
-IMPORTANT -If not using bundler and the gemfile, [install the same jekyll version that GitHub Pages is using](https://pages.github.com/versions/).
+## Pull requests
-## Create R Documentation:
-
-##### In `documentation/_posts/r`
-1. Write your tutorial in R Markdown (Rmd) file (**IMPORTANT:** do not edit the markdown (md) files by hand! All edits should happen in the .Rmd file! The *only* exception to this is the index file: `2015-07-30-r-index.md` which you should edit directly.)
- - Your .Rmd file should be named in the following format: `yyyy-mm-dd-chart-type.Rmd`
- - Please base your tutorial off of one of our existing tutorials (i.e. `documentation/_posts/r/2015-11-19-shapes.Rmd`)
- - Include the following header (*replacing `your-tutorial-chart` with the type of chart you're creating in the tutorial.) :
- ```
- ---
- name: Your-Tutorial-Chart
- permalink: r/your-tutorial-chart/
- description: How to create your-tutorial-chart in R. Short description of your tutorial.
- layout: base
- thumbnail: thumbnail/your-tutorial-chart.jpg *see step 2 for further thumbnail instructions*
- language: r
- page_type: example_index
- display_as: chart_type
- order: 3 *see below for order instructions*
- output:
- html_document:
- keep_md: true
- ---
- ```
- *`order` defines the order in which the tutorials appear on plot.ly/r. Please take a look at https://plotly.com/r/ and order your tutorial next to similar chart types.
- - Under the header, include the following r code snippet:
-
- ```
- ```{r, echo = FALSE, message=FALSE}
- knitr::opts_chunk$set(message = FALSE, warning=FALSE)
- ```
-
- - If your example needs to authenticate with Chart Studio, use the following R code snippet instead:
-
- ```
- ```{r, echo = FALSE, message=FALSE}
- knitr::opts_chunk$set(message = FALSE, warning=FALSE)
- Sys.setenv("plotly_username"="RPlotBot")
- Sys.setenv("plotly_api_key"="q0lz6r5efr")```
- ```
-
- - To include R code and plots in your tutorial, format the code snippets and plots in the following format:
-
- ```
- ```{r}
- library(plotly)
- #Add your R Code Here i.e.:
- p <- plot_ly(economics, x = ~date, y = ~uempmed, name = "unemployment")
- p```
- ```
-
- ```
-
-2. Convert the `.Rmd` file to a `.md` file.
- - Single `.Rmd` file: `Rscript -e "rmarkdown::render('YOUR_FILE_.RMD', output_dir='OUTPUT_DIRECTORY')"` in your terminal.
-
- -Convert all the `.Rmd` files in a given directory: `for i in R_FILE_PATH/*.Rmd; do Rscript -e "rmarkdown::render('$i', output_dir='OUTPUT_DIRECTORY')"; done` in your terminal.
-
-3. 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 `documentation`
-4. Make a PR
-
- - Ready for your changes to be reviewed? Make a pull request against the `master` 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 [graphing-library-docs](https://github.com/plotly/graphing-library-docs) repository and open a pull request against the `master` branch. You can then tag **@jdamiba** for a review.
-
-5. To proof your work follow these steps: https://github.com/plotly/graphing-library-docs/blob/master/Contributing.md#rendering-the-pages-locally
-
-##### At https://plotly.com/r
-6. Your changes haven't been deployed yet so they won't be online. That said, PLEASE visit https://plotly.com/r/your-tutorial and make sure everything looks correct once they have been deployed.
-
- - Some common problems that you should check for:
- - Make sure all plots appear!
- - The thumbnail image appears on: https://plotly.com/r/
+Open a pull request against the `master` branch of [plotly/graphing-library-docs](https://github.com/plotly/graphing-library-docs) for changes to the R landing pages, or against [plotly/plotly.r-docs](https://github.com/plotly/plotly.r-docs) for changes to tutorial content. A Plotly maintainer will review.
## 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/graphing-library-docs/blob/master/make_instructions.txt) for more information on how search works and instructions on how to update or edit Plotly search indices.
-
-Thanks for contributing to our documentation!!
+Search on https://plotly.com/r/ is powered by an Algolia index that is updated separately. See the [Search indices section of the main README](https://github.com/plotly/graphing-library-docs/blob/master/README.md#search-indices) for how to update the R search index.
diff --git a/make_instructions.txt b/make_instructions.txt
deleted file mode 100644
index cf50eb52a..000000000
--- a/make_instructions.txt
+++ /dev/null
@@ -1,101 +0,0 @@
-#################
-MAKE INSTRUCTIONS
-#################
-
-Contents:
-
- Overview
-
- Setup
-
- FAQ
-
- Available targets
-
-################################################################################
-
-Overview
-
- The functions found in this makefile are associated with the Algolia search
- indices which provide search functionality on Plotly's documentation pages.
-
- We have multiple search indices:
- - js_docs (https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/js_docs)
- - Search on: https://plotly.com/javascript/
- - Includes html files found in documentation/_posts/javascript
- - Update by running `make update_js_search` locally from the root of
- the documentation repo
- - python_docs (https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/python_docs)
- - Search on: https://plotly.com/python/ and https://plotly.com/pandas/
- - Includes html files found in documentation/_posts/python
- - Update by running `make update_python_search` locally from the root of
- the documentation repo
- - r_docs (https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/r_docs)
- - Search on: https://plotly.com/r/ and https://plotly.com/ggplot2/
- - Includes md files found in documentation/_posts/r and
- documentation/_posts/ggplot2
- - Update by running `make update_r_search` locally from the root of
- the documentation repo
- - schema (https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/schema)
- - Search on chart attribute reference pages
- (i.e.: https://plotly.com/javascript/reference,
- https://plotly.com/matlab/reference, https://plotly.com/python/reference
- https://plotly.com/r/reference)
- - Includes all schema from plotly.js (https://api.plot.ly/v2/plot-schema)
- - Update by running `make update_ref_search` locally from the root of
- the documentation repo
-
-################################################################################
-
-################################################################################
-
-Setup
-
- In order to update the indices you will need to have Ruby and Jekyll
- installed. For more information on setting up these tools see our
- documentation contributing guide:
- https://github.com/plotly/graphing-library-docs/blob/master/Contributing.md
- Additionally, you will need to set the Algolia API KEY as an environment
- variable on your local machine. This key should remain private, please
- contact chelsea@plot.ly for the key or more information.
-
-################################################################################
-
-################################################################################
-
-FAQ
-
- How to Update:
- You can update the index of your choice by running the available target
- functions (for example: `make update_python_search`) listed below from
- the root of the documentation repo (i.e. the same path as this file).
-
- When to Update:
- The search index should be updated when a new doc is added to the associated
- directory (i.e. run `make update_python_search` when adding a NEW html file
- to documentation/_posts/python.) The schema index should be updated when a
- new plotly.js version is added to streambed.
-
- How to Exclude Files from the Search Index:
- Each search index has an associated _config.yml (i.e. _config_js_search.yml,
- _config_python_search.yml, _config_r_search.yml). In the associated .yml file
- under algolia there is a list of excluded files. You can add any files or paths
- that should not be included in the search to that list.
-
-################################################################################
-
-################################################################################
-
-Available targets (i.e. $ make target):
-
- search_readme -> `less` this file
-
- update_js_search -> update the plotly.js search index: https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/js_docs
-
- update_python_search -> update the python search index: https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/python_docs
-
- update_r_search -> update the r search index: https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/r_docs
-
- update_ref_search -> update the schema search index: https://www.algolia.com/apps/7EK9KHJW8M/explorer/browse/schema
-
-################################################################################
diff --git a/makefile b/makefile
index e75298687..bf64b72c9 100644
--- a/makefile
+++ b/makefile
@@ -1,15 +1,36 @@
-all : search_readme
+.PHONY: help all setup update_js_search update_python_search update_r_search update_ref_search fetch_adjacent_python_files fetch_upstream_files clean
-search_readme :
+all: help
+
+help: ## Show this help (list available targets)
+ @echo ""
+ @echo "Available targets:"
+ @echo ""
+ @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+ | awk 'BEGIN {FS = ":.*?## "} {printf " \033[36m%-30s\033[0m %s\n", $$1, $$2}'
+ @echo ""
+ @echo "See README.md for setup instructions and the 'Search indices' section for details on the search targets."
+ @echo ""
+
+setup: ## Install all dependencies needed to build the site locally (gems, Python, Node, upstream content)
+ @echo "Installing Ruby gems..."
+ gem install bundler
+ bundle install
+ @echo "Installing Python packages..."
+ pip install -r requirements.txt
+ @echo "Installing Node packages..."
+ npm install
+ @echo "Fetching upstream documentation content..."
+ $(MAKE) fetch_upstream_files
@echo ""
- less make_instructions.txt
+ @echo "Setup complete. Run 'bundle exec jekyll serve --config _config_dev.yml' to start the dev server."
-update_js_search :
+update_js_search: ## Update the plotly.js Algolia search index
@echo "Updating js_docs search index"
python update_js_docs_search.py
-update_python_search :
+update_python_search: ## Update the Python Algolia search index
@echo "Updating python_docs index"
rm -rf plotly.py _posts/python/html
git clone git@github.com:plotly/plotly.py --branch=doc-prod --depth=1
@@ -18,7 +39,7 @@ update_python_search :
bundle exec jekyll algolia push --config _config_python_search.yml
rm -rf plotly.py _posts/python/html
-update_r_search :
+update_r_search: ## Update the R/ggplot2 Algolia search index
@echo "Updating r_docs index"
rm -rf plotly.r-docs _posts/r/md _posts/ggplot2/md
git clone git@github.com:plotly/plotly.r-docs --branch=master --depth=1
@@ -28,15 +49,11 @@ update_r_search :
bundle exec jekyll algolia push --config _config_r_search.yml
rm -rf plotly.r-docs _posts/r/md _posts/ggplot2/md
-update_ref_search :
+update_ref_search: ## Update the schema (reference-pages) Algolia search index
@echo "Updating search for reference pages"
python update_ref_search.py
-fetch_adjacent_python_files:
- rm -rf _posts/python/html
- cp -r ../plotly.py/doc/build/html _posts/python/html
-
-fetch_upstream_files: clean
+fetch_upstream_files: clean ## Fetch upstream tutorial content (Python, R, ggplot2, Julia, Matlab, C#, F#)
git clone --depth 1 -b built https://github.com/plotly/plotly.py-docs _posts/python/html
git clone --depth 1 -b built https://github.com/plotly/plotlyjs.jl-docs _posts/julia/html
git clone --depth 1 -b built https://github.com/plotly/plotly.net-docs _posts/fsharp/html
@@ -45,7 +62,11 @@ fetch_upstream_files: clean
mv _posts/r/md/ggplot2 _posts/ggplot2/md
mv _posts/fsharp/html/csharp _posts/csharp/html
-clean:
+fetch_adjacent_python_files: ## Copy Python docs from an adjacent ../plotly.py checkout (faster than fetch_upstream_files for Python)
+ rm -rf _posts/python/html
+ cp -r ../plotly.py/doc/build/html _posts/python/html
+
+clean: ## Remove all fetched upstream content
rm -rf _posts/python/html
rm -rf _posts/julia/html
rm -rf _posts/fsharp/html
diff --git a/requirements.txt b/requirements.txt
index ea2559303..dc0423c15 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,2 +1,3 @@
+PyYAML==6.0.1
+python-frontmatter==0.5.0
algoliasearch==1.20.0
-python-frontmatter==0.4.5
diff --git a/style_README.md b/style_README.md
index ec3f5c178..cd0b8a680 100644
--- a/style_README.md
+++ b/style_README.md
@@ -1,33 +1,28 @@
# Styles
-The styling for this repo is broken up into two different parts: [gulp](https://github.com/plotly/graphing-library-docs/blob/master/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)
+The styling for this repo is broken up into two different parts: [gulp](https://github.com/plotly/graphing-library-docs/blob/master/gulpfile.js) + browsersync + sass, and vanilla css.
## gulp + browsersync + scss
-This repo is set up to run with a [gulp](https://github.com/plotly/graphing-library-docs/blob/master/gulpfile.js) + sass + browsersync workflow. Essentially what this does is leverages a local server to display the site and when you make updates to the scss files they will be live injected into the site to see the immediate effects of your changes.
+This repo is set up to run with a [gulp](https://github.com/plotly/graphing-library-docs/blob/master/gulpfile.js) + sass + browsersync workflow. It leverages a local server to display the site, and live-injects scss changes so you can see the immediate effects of your edits.
-The scss and jekyll instance have been separated to allow for faster updates to the scss independent of the markup.
+The scss and Jekyll instance have been separated to allow for faster updates to the scss independent of the markup.
### Usage
-Once the repo has been cloned successfully (see [Contributing.md](https://github.com/plotly/graphing-library-docs/blob/master/Contributing.md)), run `$ npm install` to install gulp and the necessary dependencies.
-
-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)
+Once you have successfully cloned the repo (see the main [README.md](https://github.com/plotly/graphing-library-docs/blob/master/README.md#how-to-get-the-application-working-locally)), run `npm install` to install gulp and the necessary dependencies.
-OR
+Generally it's best to work with two terminal sessions: one for `bundle exec jekyll …` and another to keep the `gulp` task running.
-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
+1. Run `bundle exec jekyll serve --config _config_dev.yml` to create a local server at http://localhost:4000 that browsersync leverages (see `gulpfile.js` to adjust as needed)
+2. Run `gulp` in the other terminal
+3. Make any updates to the scss files
### markup + scss workflow
-It's a bit of a hassle to make concurrent updates to markup and scss. Anytime you update an html/js file you'll have to run a `$ jekyll build` command or `$ jekyll serve` and have jekyll watching for changes. I have found issues with jekyll's watch being too sensitive and have opted to build when I choose to prevent long hangs because of the size of the repo.
-When you run a `$ jekyll` you need to update any scss file as jekyll will automatically replace the styles.css file. e.g.: if you modify any scss file and save it, it will overwrite the file jekyll has produced.
+It's a bit of a hassle to make concurrent updates to markup and scss. Any time you update an html/js file you'll have to run `bundle exec jekyll build` (or run `bundle exec jekyll serve` with Jekyll watching for changes). Jekyll's watch mode can be slow on this repo because of its size; building on demand is sometimes preferable.
+
+When you run `bundle exec jekyll …`, Jekyll regenerates `styles.css` — so if you modify any scss file and save it, Jekyll's output may overwrite your changes. Run `gulp build` again to regenerate the css after Jekyll runs.
### folder structure
@@ -55,13 +50,11 @@ When you run a `$ jekyll` you need to update any scss file as jekyll will automa
## 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 [version](https://github.com/plotly/graphing-library-docs/blob/master/_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 master` to add your updates to the repo.
+ - Run `gulp build` in the root of the documentation repo after making any scss edits. This will update `main.css` as well as the [cache-bust version](https://github.com/plotly/graphing-library-docs/blob/master/_data/cache_bust_css.yml) which is used to prevent css caching.
+ - Open a pull request with your scss changes plus the generated `main.css` and `cache_bust_css.yml`. A maintainer will review and merge it.
## vanilla css
-If there's no need or desire to utilize the scss workflow, there's a separate css file added to add quick and simple fixes or updates to the repo.
+If there's no need or desire to utilize the scss workflow, there's a separate css file added for quick and simple fixes or updates to the repo.
`/all_static/css/css.css`
-
-Last updated: 05.09.2016