|
1 | | -# Contributing |
2 | | - |
3 | | -We very much welcome contributions! If you have an idea or proposal for a new |
4 | | -tutorial, please [open an issue](https://github.com/numpy/numpy-tutorials/issues) |
5 | | -with an outline. |
6 | | - |
7 | | -Don’t worry if English is not your first language, or if you can only come up |
8 | | -with a rough draft. Open source is a community effort. Do your best – we’ll help |
9 | | -fix issues. |
10 | | - |
11 | | -Images and real-life data make text more engaging and powerful, but be sure what |
12 | | -you use is appropriately licensed and available. Here again, even a rough idea |
13 | | -for artwork can be polished by others. |
14 | | - |
15 | | -## Building the website |
16 | | - |
17 | | -```{note} |
18 | | -The NumPy tutorials are powered by [`jupyter-book`][jb-docs] and the |
19 | | -[`MyST` document engine][mystmd]. |
20 | | -See the linked documentation for further details. |
| 1 | +```{include} ../CONTRIBUTING.md |
21 | 2 | ``` |
22 | | - |
23 | | -[jb-docs]: https://jupyterbook.org/stable/ |
24 | | -[mystmd]: https://mystmd.org/ |
25 | | - |
26 | | -### Quickstart |
27 | | - |
28 | | -Set up a development environment with the dependencies listed in |
29 | | -`requirements.txt` and `site/requirements.txt`. |
30 | | -For example, using the built-in [`venv`][venv] module: |
31 | | - |
32 | | -```bash |
33 | | -python -m venv np-tutorials |
34 | | -source np-tutorials/bin/activate |
35 | | -python -m pip install -r requirements.txt -r site/requirements.txt |
36 | | -``` |
37 | | - |
38 | | -[venv]: https://docs.python.org/3/library/venv.html |
39 | | - |
40 | | -The site can then be built with: |
41 | | - |
42 | | -```bash |
43 | | -jupyter-book start --execute |
44 | | -``` |
45 | | - |
46 | | -This will execute all the notebooks and start a web server to view the rendered |
47 | | -content locally. |
48 | | -View the rendered site by opening the ``localhost:30xy`` in your preferred browser (the exact port number will be printed in your terminal). |
49 | | - |
50 | | -## Adding your own tutorials |
51 | | - |
52 | | -If you have your own tutorial in the form of a Jupyter notebook (an `.ipynb` |
53 | | -file) and you'd like to try add it out to the repository, follow the steps below. |
54 | | - |
55 | | -### Create an issue |
56 | | - |
57 | | -Go to <https://github.com/numpy/numpy-tutorials/issues> and create a new issue |
58 | | -with your proposal. |
59 | | -Give as much detail as you can about what kind of content you would like to |
60 | | -write (tutorial, how-to) and what you plan to cover. |
61 | | -We will try to respond as quickly as possible with comments, if applicable. |
62 | | - |
63 | | -### Check out our suggested template |
64 | | - |
65 | | -You can use this template to make your content consistent with our existing |
66 | | -tutorials. |
67 | | - |
68 | | -### Upload your content |
69 | | - |
70 | | -Remember to clear all outputs on your notebook before uploading it. |
71 | | - |
72 | | -<ul> |
73 | | -<details> |
74 | | - <summary> |
75 | | - <b>Fork this repository</b> (if you haven't before). |
76 | | - </summary> |
77 | | - <img src="_static/01-fork.gif" width=80% height=80%> |
78 | | -</details> |
79 | | - |
80 | | -<details> |
81 | | - <summary> |
82 | | - <b>In your own fork, create a new branch for your content.</b> |
83 | | - </summary> |
84 | | - <img src="_static/02-create_new_branch.gif" width=80% height=80%> |
85 | | -</details> |
86 | | - |
87 | | -<details> |
88 | | - <summary> |
89 | | - <b>Add your notebook to the <code>content/</code> directory.</b> |
90 | | - </summary> |
91 | | - <img src="_static/03-upload.gif" width=80% height=80%> |
92 | | -</details> |
93 | | - |
94 | | -<b>Update the <code>environment.yml</code> file with the dependencies for your tutorial</b> |
95 | | -(only if you add new dependencies). |
96 | | - |
97 | | -<details> |
98 | | - <summary> |
99 | | - <b>Update this <code>README.md</code> to include your new entry.</b> |
100 | | - </summary> |
101 | | - <img src="_static/04-add_to_readme.gif" width=80% height=80%> |
102 | | -</details> |
103 | | - |
104 | | -<details> |
105 | | - <summary> |
106 | | - <b>Create a <a href="https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests">pull request.</a> Make sure the "Allow edits and access to secrets by maintainers" option is selected so we can properly review your submission.</b> |
107 | | - </summary> |
108 | | - <img src="_static/05-create_PR.gif" width=80% height=80%> |
109 | | -</details> |
110 | | - |
111 | | -🎉 <b>Wait for review!</b> |
112 | | -</ul> |
113 | | - |
114 | | -For more information about GitHub and its workflow, you can see |
115 | | -[this document][collab]. |
116 | | - |
117 | | -[collab]: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests |
0 commit comments