Skip to content

Commit 6df62ce

Browse files
daexsdaexs
committed
Updated docs/CONTRIBUTING.md with Mkdocs build instructions and removed old instructions from the old build.
1 parent bddd3cd commit 6df62ce

File tree

1 file changed

+63
-123
lines changed

1 file changed

+63
-123
lines changed

‎docs/CONTRIBUTING.md‎

Lines changed: 63 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -2,150 +2,90 @@
22

33
Plotly welcomes contributions to its [open-source JavaScript graphing libraries documentation](https://plotly.com/javascript) from its community of users.
44

5-
Our JavaScript tutorials are written in HTML files in the `_posts/plotly_js` directory of this repository.
5+
Our JavaScript tutorials are written in HTML files in the `docs/content/` directory of this repository.
66

77
## Contribute Quickly to Plotly's JavaScript Graphing Library Documentation
88

9-
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. This can be done using the GitHub graphical user interface at https://github.com/plotly/graphing-library-docs.
9+
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. This can be done using the GitHub graphical user interface at https://github.com/plotly/plotly.js/.
1010

1111
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:
1212

1313
![Screen Shot 2020-01-07 at 12 45 39 PM](https://user-images.githubusercontent.com/1557650/71916356-bfe53800-314b-11ea-92b6-eb763037f6d5.png)
1414

1515
**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.
1616

17-
## Develop Locally
17+
## Mkdocs Setup
1818

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.
19+
Before proceeding, make sure you are working in the `docs` directory. This is where all of the files needed
20+
to build the site using Mkdocs are.
2021

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.**
22+
### Create a Virtual Environment
2223

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.
24+
Create a *virtual environment* for the project so that packages you install won't affect other projects you are working on.
25+
We recommend using [`uv`](https://docs.astral.sh/uv/) for this:
2426

25-
## Create An Index Page For A New Chart Type:
27+
```bash
28+
uv venv --python 3.12
29+
source .venv/bin/activate
30+
```
31+
32+
Alternatively,
33+
you can use [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands)
34+
or [virtualenv](http://docs.python-guide.org/en/latest/dev/virtualenvs/)
35+
to create and manage your virtual environment;
36+
see those tools' documentation for more information.
2637

27-
If you are documenting a new chart type, then you need to create an index page for it before creating the actual example page.
38+
### Install Packages
2839

29-
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`).
40+
If you are using `uv`, you can install the dependencies using this command:
3041

31-
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!
42+
```bash
43+
uv pip install -r requirements.txt
3244
```
33-
---
34-
name: Add-Chart-Type-or-Topic
35-
permalink: javascript/add-chart-type-or-topic/
36-
description: How to make a D3.js-based add-chart-type-or-topic in javascript. Add an additional sentence summarizing chart-type or topic.
37-
layout: langindex
38-
thumbnail: thumbnail/mixed.jpg
39-
language: plotly_js
40-
page_type: example_index
41-
display_as: **SEE BELOW
42-
order: 5
43-
---
44-
{% assign examples = site.posts | where:"language","plotly_js" | where:"suite","add-chart-type-or-topic"| sort: "order" %}
45-
{% include posts/auto_examples.html examples=examples %}
45+
46+
If you are using `conda` or `virtualenv`, you can install all dependencies with:
47+
48+
```bash
49+
pip install -r requirements.txt
4650
```
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!
4851

49-
- Index pages for chart categories must have `order: 5`.
52+
### File Structure
5053

51-
## Create A New Example Post:
54+
- `build/` is where Mkdocs builds the local copy of the site. This is only updated if you run `mkdocs build`.
55+
- `tmp/` includes the generated HTML snippets for examples and reference pages. `make examples` builds the HTML files in `tmp/javascript/` while `make reference` builds the HTML files in `tmp/reference/`.
56+
- `pages/` is where Mkdocs looks for content to build the site. It includes markdown files that uses `pymdownx.snippets` syntax to insert the HTML snippets from `tmp/` and handwritten files such as `pages/plotlyjs-function-reference.md` for the Quick Reference section in the navigation. It also includes the custom css files used for styling (`pages/css/`), extra javascript files (`pages/javascript`), and HTML files that override Mkdocs templates to add custom functionality (`pages/overrides/`). There is one special case in `static-image-export.md` that uses `img.show()`. To insert the images into the markdown file, `bin/run_markdown.py` saves the images into `pages/imgs/`.
57+
- `mkdocs.yml` contains the configuration for the Mkdocs build such as extensions, site name and navigation.
5258

53-
1. In the folder containing the examples for the chart type you are writing documentation for, create a file named: `yyyy-mm-dd-example-title.html`.
5459

55-
2. Copy the example post template below and write JavaScript code to demonstrate the feature you are documenting.
56-
- 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.
57-
- If `plot_url` front-matter is present, then the URL given will be embedded in an `iframe` below the example.
58-
```
59-
---
60-
description: How to make a D3.js-based bar chart in javascript. Seven examples of
61-
grouped, stacked, overlaid, and colored bar charts.
62-
display_as: basic
63-
language: plotly_js
64-
layout: base
65-
name: Bar Charts
66-
order: 3
67-
page_type: example_index
68-
permalink: javascript/bar-charts/
69-
redirect_from: javascript-graphing-library/bar-charts/
70-
thumbnail: thumbnail/bar.jpg **MORE INFO ON ADDING THUMBNAILS BELOW
71-
markdown_content: |
72-
indented content in markdown format which will prefix an example ****SEE BELOW
73-
---
74-
var data = [
75-
{
76-
x: ['giraffes', 'orangutans', 'monkeys'],
77-
y: [20, 14, 23],
78-
type: 'bar'
79-
}The
80-
];
81-
82-
Plotly.newPlot('myDiv', data);
83-
```
60+
### Building the Site
61+
62+
Before building the site, you need to generate the HTML snippets found in `tmp/` that the mkdocs build depends on. This can be done by running both `make examples` and `make reference` which will create HTML snippets in `tmp/javascript/` and `tmp/reference/` respectively.
63+
64+
If you ever add more HTML snippets generated into any of those folders, you may need to add more markdown files to `pages/` to add a new page. To do this, you can rerun the script that generates each markdown file with the `pyxmdown.snippets` syntax to insert the HTML snippets. You can do this by running the `bin/generate_reference_pages.py` script.
65+
66+
Run `mkdocs build` to rebuild the local copy of the site in `build/` or `mkdocs serve` to run the site on local host.
67+
68+
69+
### Macros
70+
71+
In `mkdocs.yml`, the `extra` section defines configuration values used across the documentation. For example, you can specify the Plotly.js version in `extra.js_version`. The `macros` plugin makes `js_version` accessible in scripts such as `bin/examples_pages.py` when CodePen examples are being embedded into the HTML snippets generated into `tmp/javascript`.
72+
73+
74+
## Overriding Mkdocs material themes
75+
76+
To modify the HTML components of the Mkdocs site, copy the template from the [`mkdocs-material` repository](https://github.com/squidfunk/mkdocs-material/tree/master/material/templates). Then, make these changes in `pages/overrides`.
77+
78+
You can either modify the existing files in `pages/overrides` or add a new file, paste the template for the component you are modifying and make your changes. Make sure to use the same file structure as the `mkdocs-material` default theme.
79+
80+
For example, to change the footer, copy the `footer.html` template from the [`mkdocs-material` repository](https://github.com/squidfunk/mkdocs-material/blob/master/material/templates/partials/footer.html), then create a `footer.html` file under `pages/overrides/partials/`, paste and modify it.
81+
82+
See [the official documentation](https://squidfunk.github.io/mkdocs-material/customization/) for more details.
83+
84+
85+
## Mkdocs Validation
86+
87+
In `mkdocs.yml`, there is a section `validation` that defines how Mkdocs presents any issues and resolves links. When you build the site, there are some `INFO` logs that can be ignored.
88+
89+
`Doc file <source_file_name>.md contains an unrecognized relative link '../<target_file_name>/', it was left as is` is an `INFO` log that happens because Mkdocs cannot resolve the link during build, but when the site is running, the redirects defined in `mkdocs.yml` will make sure these links redirect to the proper page. If a redirect does not exist for the page referenced in the link, then it is a regular missing page error and needs to be fixed.
8490

85-
- `display_as` sets where your tutorial is displayed. Make sure to update `_includes/posts/documentation_eg.html` with the new chart type!:
86-
- 'file_settings' = https://plotly.com/javascript/plotly-fundamentals
87-
- 'basic' = https://plotly.com/javascript/basic-charts
88-
- 'statistical' = https://plotly.com/javascript/statistical-charts
89-
- 'scientific' = https://plotly.com/javascript/scientific-charts
90-
- 'financial' = https://plotly.com/javascript/financial-charts
91-
- 'maps' = https://plotly.com/javascript/maps
92-
- '3d_charts' = https://plotly.com/javascript/3d-charts
93-
- See additional options [HERE](https://github.com/plotly/graphing-library-docs/blob/master/_includes/posts/documentation_eg.html#L1)
94-
95-
- `order` defines the order in which the tutorials appear in each section on plot.ly/javascript.
96-
- <b>Note</b> The `order` of posts within a `display_as` must be a set of consecutive integers (i.e. [1, 2, 3, 4, 5, 6, ...]).
97-
- 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.
98-
99-
- `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.
100-
101-
- Thumbnail images should named `your-tutorial-chart.jpg` and be *EXACTLY* 160px X 160px.
102-
- posts in the following `display_as` categories **MUST** have a thumbnail
103-
- 'file_settings' = https://plotly.com/javascript/plotly-fundamentals
104-
- 'basic' = https://plotly.com/javascript/basic-charts
105-
- 'statistical' = https://plotly.com/javascript/statistical-charts
106-
- 'scientific' = https://plotly.com/javascript/scientific-charts
107-
- 'financial' = https://plotly.com/javascript/financial-charts
108-
- 'maps' = https://plotly.com/javascript/maps
109-
- '3d_charts' = https://plotly.com/javascript/3d-charts
110-
- 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.
112-
- Log-in here: https://661924842005.signin.aws.amazon.com/console
113-
- 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
115-
116-
## Modify An Existing Post:
117-
118-
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.
119-
120-
# Best Practices:
121-
- `order` examples from basic to advanced
122-
- avoid the use of global JavaScript variables for `data` and `layout`.
123-
- make the chart display in a DOM element named `myDiv`
124-
- use the `.newPlot()` function
125-
- use "real" data to make the examples realistic and useful for users.
126-
- avoid using random or dummy data as much as humanly possible! Should only be a last resort.
127-
- 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.
128-
- 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.
129-
130-
## Make a Pull Request
131-
- Ready for your changes to be reviewed? Make a pull request!
132-
133-
- Create a feature branch and use `git status` to list changed files.
134-
```
135-
git checkout -b your_feature_branch
136-
git status
137-
```
138-
- Add, commit, and push the files that you'd like to add to your PR:
139-
```
140-
git add file-a
141-
git add file-b
142-
git commit -m 'message about your changes'
143-
git push origin your_feature_branch
144-
```
145-
- Visit the [documentation repo](https://github.com/plotly/graphing-library-docs) and open a pull request!. You can then tag **@jdamiba** for a review.
146-
147-
## Style Edits
148-
149-
Please refer to our [Styles README](https://github.com/plotly/graphing-library-docs/blob/master/style_README.md)
150-
151-
Thanks for contributing to our documentation!!
91+
Any internal references in the markdown files, are resolved by Mkdocs relative to `docs/`. So, absolute links will be correctly resolved when the site is running. This is configured `mkdocs.yml` with the line `absolute_links: relative_to_docs`.

0 commit comments

Comments
 (0)