-
Notifications
You must be signed in to change notification settings - Fork 0
/
pythons-doctest.html
87 lines (72 loc) · 4.81 KB
/
pythons-doctest.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
<!DOCTYPE html>
<html lang="en">
<head>
<title></title>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta id="keywords" name="keywords" content="">
<link id="stylesheet" rel="stylesheet" type="text/css" href="https://oskipa.github.io/theme/css/code.css"></link>
<link id="stylesheet" rel="stylesheet" type="text/css" href="https://oskipa.github.io/theme/css/site.css"></link>
</head>
<body>
<header class="header">
<h1 class="site-name">
<a class="home-link" href="https://oskipa.github.io">Dada</a><br />
|> Structures<br />
|> Algorithms</h1>
<nav>
<menu class="minimal-menu">
<li><a href="https://oskipa.github.io/pages/today-i-learned.html">til</a></li>
<li><a href="https://oskipa.github.io/pages/now.html">now</a></li>
<li><a href="https://oskipa.github.io/short_index.html">index</a></li>
<!--
<li><a href="category/log.html">web log<a></li>
<li><a href="">about<a></li>
<li><a href="">site map<a></li>
-->
</menu>
</nav>
</header>
<div class="container">
<div class="row">
<div class="col-md-8">
<h2>Python's doctest</h2>
<h3>How to quickly start writing examples that you can test in your docs</h3>
<label>31 July, 2020</label>
<h3>tldr</h3>
<p><a href="https://docs.python.org/3/library/doctest.html">doctest</a> [1] is a library that allows you to write python examples in comments or text documents. This is handy because you can write examples, test them, and have the peace of mind that they work. </p>
<p>Here are some examples example</p>
<div class="highlight"><pre><span></span><code> >>> print("Hello World!")
Hello World!
>>> def one_plus_one():
<span class="k">...</span> return 1 + 1
...
>>> one_plus_one()
2
</code></pre></div>
<p>As you can see, the key is to use the three arrows, >>>, to write the python that you would execute in the console. The result is written lined up after the >>> prompt. If you have a multi-line code sample, like when you are writing a function, you must enter the three dots, ... , and then line up the code as you would when writing python.</p>
<p>To test your code, you need to have a script that imports doctest. I looked it up on the internet. The solution I found was</p>
<div class="highlight"><pre><span></span><code> <span class="o">%</span> <span class="n">python3</span> <span class="o"><<</span> <span class="n">EOF</span>
<span class="kn">import</span> <span class="nn">doctest</span>
<span class="n">doctest</span><span class="o">.</span><span class="n">testfile</span><span class="p">(</span><span class="s1">'pythons_doctest.md'</span><span class="p">)</span>
<span class="n">EOF</span>
</code></pre></div>
<p>This is enough to get you going. Of course there is a lot more to it. Please consult [1] for more information.</p>
<h3>The long story</h3>
<p>One of the most awkward bits when writing about programming is writing examples in your articles and having to copy-and-past them into a script, run them, and then having to fix your article. It is not difficult. It is cumbersome. You leave a text editor to go into the console and you must add libraries and whatever you need to prepare to run the examples.</p>
<p>doctest makes it easier to write your examples in the docs. Or you could write the examples on the interactive console and copy-and-paste the expressions and results into the document you are writing. I first learned about these libraries from Elixir, which encourages writing documentation with examples that can be tested with their document testing library. As I started writing these small entries on Python, I decided that it would be handy to have examples that can be tested before I publish them.</p>
<p>References:</p>
<p>[1] <em>doctest -- Test interactive Python examples</em> docs.python.org <a href="https://docs.python.org/3/library/doctest.html">https://docs.python.org/3/library/doctest.html</a> (accessed, July 31, 2020)</p>
</div>
</div>
</div>
<footer class="footer">
<!-- <p class="about"><a href="http://hugoestr.github.io/blog/manifesto.html">About</a> --> <a href="https://oskipa.github.io/pages/about.html" >I am</a> a software developer. I code in Python, Ruby, Lisp, and many other languages. I like poetry, museums, and ukuleles. I try to guide my life on principles of dadaism and nonviolence.</p>
<p>
<a href="feeds/all.atom.xml">atom</a>
<!-- <a href="http://github.com/oskipa/">github</a> -->
</p>
<p>Artisanally built with <a href="https://blog.getpelican.com/">Pelican</a>. Content handcrafted in <a href="https://www.vim.org/" >Vim</a>. All hallucinations are human. 100% AI Free.</p>
</footer>
</body>
</html>