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
concepts and programming structures you’ve learned into practice. The
182
182
programming exercises are given at the end of each chapter, just before the
183
183
glossary. Each time there will be a skeleton code available from
184
-
<aclass="reference external" href="https://imperial-fons-computing.github.io/git.html#github-classroom-exercise" title="(in Installation instructions for FoNS v2020.0)"><spanclass="xref std std-ref">GitHubClassroom</span></a> which provides the starting
184
+
ref:<codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">GitHub</span><spanclass="pre">Classroom</span></code> which provides the starting
185
185
point. Sometimes you might be asked to complete a piece of code while on other
186
186
occasions you’ll need to write a whole Python module from scratch. Each set of
187
187
exercises will come with a matching set of tests. These are small programs which
<h3><spanclass="section-number">1.3.8. </span>Writing an issue report in Markdown on Piazza<aclass="headerlink" href="#writing-an-issue-report-in-markdown-on-piazza" title="Permalink to this headline">¶</a></h3>
426
+
<p>Web fora are often optimised for making prose easy to read, so the forum will do
427
+
things like change indentation or the location of linebreaks in order to make a
428
+
nice paragraph of text in whichever area is available on the reader’s screen.
429
+
This is great for prose, but absolutely disastrous for code or computer output,
430
+
because changing the linebreaks and other whitespace turns carefully formatted
431
+
information into scrambled junk. To overcome this, it is necessary to tell the
432
+
forum which parts of the text are prose, which are code, and possibly other
433
+
information (for example, you might want to add a mathematical formula).</p>
434
+
<p>In order to support this, many web fora support some form of markup language. A
435
+
markup language represents the structure of the contents of a body of text by
436
+
inserting special instructions, called markup, into the text. You’ve already
437
+
learned one of these systems, because <aclass="reference external" href="https://www.latex-project.org">LaTeX</a> is a markup system. The notes for
438
+
this course are written in <aclass="reference external" href="https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html">reStructuredText</a>,
439
+
which is another markup language. Many web fora, notably Piazza and GitHub, use
440
+
variants of another markup language called Markdown (computer scientists are
441
+
regrettably fond of poor puns when naming projects). Since we use Piazza in this
442
+
course we’ll look at how to use a little Markdown to make your issue reports
443
+
much more readable. It’s important to know that Markdown is not a standardised
444
+
language, so the exact functionality available depends somewhat on which forum
445
+
you are using Markdown for. For example GitHub doesn’t support typesetting maths
<h4><spanclass="section-number">1.3.8.1. </span>Setting the Piazza editor to Markdown<aclass="headerlink" href="#setting-the-piazza-editor-to-markdown" title="Permalink to this headline">¶</a></h4>
449
+
<p>When you create a new post or reply to an existing one on Piazza, the editor
450
+
which opens presents three options. Some, but not all, of the code formatting
451
+
and highlighting functionality is available via the <codeclass="code docutils literal notranslate"><spanclass="pre">Rich</span><spanclass="pre">text</span><spanclass="pre">editor</span></code>
452
+
option, which is a graphical editor more similar to Microsoft Word, so it’s
453
+
better to choose <codeclass="code docutils literal notranslate"><spanclass="pre">Markdown</span><spanclass="pre">editor</span></code>.</p>
454
+
<aclass="reference internal image-reference" href="_images/piazza_editor_choice.png"><imgalt="Image of Piazza web editor options with Markdown editor selected." class="align-center" src="_images/piazza_editor_choice.png" style="width: 50%;" /></a>
<h4><spanclass="section-number">1.3.8.2. </span>Including code, input, and output<aclass="headerlink" href="#including-code-input-and-output" title="Permalink to this headline">¶</a></h4>
458
+
<p>Code, commands you type at the terminal prompt, and output printed in the
459
+
terminal or in IPython are treated almost exactly the same way. The best
460
+
approach is to use what Markdown calls a “fenced code block”. This means that
461
+
you put the code between “fences” comprising three backquotes on a
<p>Similarly, you can mark the first fence with <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">ipython3</span></code> to indicate that the
482
+
code following is copied and pasted from an IPython command line. If you need to
483
+
include code inline in text, then you just contain it in single backquotes:
<h4><spanclass="section-number">1.3.8.3. </span>Including mathematics<aclass="headerlink" href="#including-mathematics" title="Permalink to this headline">¶</a></h4>
488
+
<p>Any text contained between delimiters comprising double dollar signs will be
489
+
passed to LaTeX and rendered as maths. For example, <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">$$x^2$$</span></code> will be rendered
490
+
as <spanclass="math notranslate nohighlight">\(x^2\)</span>.</p>
491
+
</div>
492
+
<divclass="section" id="including-links">
493
+
<h4><spanclass="section-number">1.3.8.4. </span>Including links<aclass="headerlink" href="#including-links" title="Permalink to this headline">¶</a></h4>
494
+
<p>Just dumping URLs into the text often results in hard to read code. Instead,
495
+
Markdown enables you to write the link text in square brackets followed by the
496
+
URL in round brackets. So <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">[the</span><spanclass="pre">Markdown</span><spanclass="pre">Cheat</span>
<h4><spanclass="section-number">1.3.8.5. </span>More advanced Markdown<aclass="headerlink" href="#more-advanced-markdown" title="Permalink to this headline">¶</a></h4>
502
+
<p>There are many other Markdown features that can be useful in longer posts, and
503
+
there are many resources about Markdown available online. <aclass="reference external" href="https://www.markdownguide.org">The Markdown Guide</a> is a good place to start.</p>
504
+
</div>
505
+
</div>
506
+
<divclass="section" id="an-example-issue-report">
507
+
<h3><spanclass="section-number">1.3.9. </span>An example issue report<aclass="headerlink" href="#an-example-issue-report" title="Permalink to this headline">¶</a></h3>
508
+
<p>A fairly short and simple issue report which includes all of the relevant
509
+
information, might be written in Markdown as follows. The title, which we omit
510
+
from the Markdown because it would be typed in a separate box on Piazza, might
511
+
be something like “Python square function returns wrong answer.”</p>
512
+
<divclass="highlight-markdown notranslate"><divclass="highlight"><pre><span></span>I wrote a function to square its input. I expected to see the
513
+
square of the input but I see the wrong answer.
514
+
515
+
The following code is in the file `square.py`:
516
+
517
+
```python3
518
+
def square(x):
519
+
return x^2
520
+
```
521
+
522
+
I try out this function in iPython and observe the wrong answers:
523
+
524
+
```ipython3
525
+
In [1]: from square import square
526
+
527
+
In [2]: square(2)
528
+
Out[2]: 0
529
+
530
+
In [3]: square(3)
531
+
Out[3]: 1
532
+
533
+
In [4]: square(4)
534
+
Out[4]: 6
535
+
```
536
+
537
+
I would expect to see 4, 9, 16 respectively. I do not understand what is
538
+
going wrong.
539
+
</pre></div>
540
+
</div>
541
+
<p>This results in the following, much more readable, post on Piazza:</p>
0 commit comments