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: docs/contributionTutorial.md
+14-10Lines changed: 14 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,7 @@
1
-
<b><fontcolor=#FF0000>If you follow this tutorial but find yourself stuck, please submit an issue in the <aid="tutorialIssue"href="https://github.com/OSIPI/OSIPI_CAPLEX/issues">github repository</a> and include all steps you have taken and the full traceback to the error you've encountered so we may improve this page.</font></b>
1
+
<b><fontcolor=#FF0000>If you follow this tutorial but find yourself stuck, please submit an issue in the
and include all steps you have taken and the full traceback to the error you've encountered so we may improve this page.
4
+
</font></b>
2
5
3
6
This is a basic tutorial on how to contribute to the website if you've never used github, git or written any code for a website before. You can either [use a remote environment](#work-in-a-new-development-container) via GitHub, or [use your local machine](#install-anaconda).
4
7
@@ -31,7 +34,7 @@ It is advised to use a context manager and an IDE (integrated development enviro
31
34
It is possible to install Git, VSCode and [Miniconda](https://docs.conda.io/projects/miniconda/en/latest/){target = "_blank"} (1) (lite version of Anaconda that only contains `conda`, Python and few basic packages) using `winget` on Windows if you're looking for a quick setup. Run the following commands:
32
35
{ .annotate }
33
36
34
-
1.If you still want full version of Anaconda use `winget install -e --id Anaconda.Anaconda3` instead.
37
+
If you still want full version of Anaconda use `winget install -e --id Anaconda.Anaconda3` instead.
35
38
36
39
```
37
40
winget install -e --id Git.Git
@@ -79,7 +82,7 @@ tutorial will use
79
82
`pip install mkdocs-material`(1)
80
83
{ .annotate }
81
84
82
-
1.`conda install -c conda-forge mkdocs-material`
85
+
`conda install -c conda-forge mkdocs-material`
83
86
84
87
Verify the installation by running `conda list`. You should see an alphabetically
85
88
ordered list of packages including mkdocs-material.
@@ -132,7 +135,7 @@ Navigate to [OSIPI_CAPLEX GitHub](https://github.com/OSIPI/OSIPI_CAPLEX){target
132
135
Copy the URL to your fork on github.(1) Open VSCode. On the welcome page find `Clone Git Repository` and click on it. A small window will open at the top of the screen. Paste the fork URL here.
133
136
{ .annotate }
134
137
135
-
1.For example `https://github.com/MartinKjunior/OSIPI_CAPLEX_MartinK`
138
+
For example `https://github.com/MartinKjunior/OSIPI_CAPLEX_MartinK`
136
139
137
140

138
141
@@ -153,6 +156,7 @@ Now you can open one of the files such as `contributionTutorial.md` and start ma
153
156
#### 4.2 Configure Git
154
157
155
158
In order to upload your changes you need to configure your git so that your changes may be attributed to you. If you've installed Git for Windows, you can run
159
+
156
160
```
157
161
git config --global user.name "YOUR NAME"
158
162
git config --global user.email "YOUR EMAIL"
@@ -184,7 +188,7 @@ Once you're happy with all of your changes, you need to create a pull request fo
184
188
Build a local version of the site so you can see changes take place immediately. Use the `cd` command to guide your terminal into the folder containing the `mkdocs.yml` file. You can see the current path right next to `(CAPLEX)` in your terminal (1). Once you're done, run `mkdocs serve` which will build a local version of the website. At the bottom of your terminal the final line will contain the address 127.0.0.1:8000. Hold CTRL and click on it to open in your default browser (best to move it to second monitor with VSCode open on your primary monitor). Now whenever you save any file you've worked on, the local version of the website will automatically be rebuilt.
185
189
{ .annotate }
186
190
187
-
1.When you write `cd .\` you can press **tab** to scroll through paths found in a particular folder, saving you typing long folder names. Once you **tab** to the folder you want, write another `\` and you can continue tabbing through the available subfolders.
191
+
When you write `cd .\` you can press **tab** to scroll through paths found in a particular folder, saving you typing long folder names. Once you **tab** to the folder you want, write another `\` and you can continue tabbing through the available subfolders.
@@ -205,7 +209,7 @@ The core file that builds the website is `mkdocs.yml`. It defines the authorship
205
209
The `MathJax` extension properties are defined under `extra_javascript`(1) and can be further customised by `javascripts/mathjax.js`.
206
210
{ .annotate }
207
211
208
-
1.Version of MathJax is controlled with the link `https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML-AM_CHTML` which currently is set to be the 2.7.7 version. For more info [click here](https://docs.mathjax.org/en/latest/web/start.html){target = "_blank"}.
212
+
Version of MathJax is controlled with the link `https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML-AM_CHTML` which currently is set to be the 2.7.7 version. For more info [click here](https://docs.mathjax.org/en/latest/web/start.html){target = "_blank"}.
209
213
210
214
Properties of existing objects can be modified using the `stylesheets/extra.css` file. For example, this is how we control the width of the tables shown so they use the full space provided by your monitor.
211
215
@@ -226,7 +230,7 @@ Text may be added between `<a></a>` which will be highlighted as blue and if `hr
226
230
If we wish to send the user somewhere, we can link parts of the website or add external links to text. This can be done by either using HTML anchors as discussed in `1. Adding a new anchor`, or by using `[shown text](url)`. The `url` may be a reference within the webpage, for example if `url` is `#syntax-and-commands-used-in-caplex` then [shown text](#syntax-and-commands-used-in-caplex) will send you to the title of this section. If `url` is `quantities.md#S`(1), then [shown text](quantities.md#S){target = "_blank"} will send you to the Signal quantity in the Q - Quantities section. If `url` is `https://github.com/OSIPI/OSIPI_CAPLEX` then [new website](https://github.com/OSIPI/OSIPI_CAPLEX){target = "_blank"} will be opened. For references, please use the full doi address where possible, such as `https://doi.org/10.1007/b137553`. If DOI is unavailable, please use PubMed link such as `https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2760951/`.
227
231
{ .annotate }
228
232
229
-
1.The part after `#` is the `id` or `name` of the anchor element.
233
+
The part after `#` is the `id` or `name` of the anchor element.
230
234
231
235
??? note "Opening link in a new tab"
232
236
@@ -267,7 +271,7 @@ After that, the first row may be added by adding another line of `| -- | -- | --
267
271
The data we add into the table must be part of a single line, therefore using `enter` key to create a new line would break the formatting of the table. Instead, use the HTML break symbol `<br>` to create a new line inside of a cell.(1)
268
272
{ .annotate }
269
273
270
-
1.Consider using new lines to ensure equations are shown in their entirety.
274
+
Consider using new lines to ensure equations are shown in their entirety.
271
275
272
276
??? note "Adding math equations"
273
277
@@ -290,7 +294,7 @@ Images are added using the syntax<br>
290
294
with an optional configuration inside `{}`(1) at the end. For example, <br>`{ width="100" }` will create
291
295
{ .annotate }
292
296
293
-
1.Multiple configurations should all be included within a single `{}` with spaces between, e.g. `{ width="100" align=right }`.
297
+
Multiple configurations should all be included within a single `{}` with spaces between, e.g. `{ width="100" align=right }`.
@@ -314,7 +318,7 @@ To enhance user experience, we provide a button to copy the URL as a reference t
314
318
315
319
</div>
316
320
317
-
1.The base class we use is `md-button`. To create an extension to its properties you can add a new class such as <br>`md-button--example`. In `extra.css` this would look like <br>`.md-button.md-button--example {}` which translates to <br>`class="md-button md-button--example"` (note a whitespace instead of `.`) in the HTML code.
321
+
The base class we use is `md-button`. To create an extension to its properties you can add a new class such as <br>`md-button--example`. In `extra.css` this would look like <br>`.md-button.md-button--example {}` which translates to <br>`class="md-button md-button--example"` (note a whitespace instead of `.`) in the HTML code.
318
322
319
323
The button builds the hyperlink using the `id=` of the anchor inside the closest table row (`tr` element). Consider the table row<br>
0 commit comments