def test_to_html(self):
text = '''# Title
`pdoc.Module` is a `Doc`, not `dict`.
```
code block
```
reference: `package.foo`
'''
expected = '''<h1 id="title">Title</h1>
<p><a href="#pdoc.Module">Module</a> is a <a href="#pdoc.Doc">Doc</a>, not <code>dict</code>.</p>
<pre><code>code block
</code></pre>
<p>reference: <a href="/package.foo.ext">package.foo</a></p>'''
module = pdoc.Module(pdoc)
def link(dobj, *args, **kwargs):
return '<a href="{}">{}</a>'.format(dobj.url(relative_to=module),
dobj.qualname)
html = to_html(text, module=module, link=link)
self.assertEqual(html, expected)
self.assertIn('<a href=',
to_html('`pdoc.Doc.url()`', module=module, link=link))
self.assertIn('<code>foo.f()</code>',
to_html('`foo.f()`', module=module, link=link))
def test_doctests(self):
expected = '''<p>Need an intro paragrapgh.</p>
<pre><code>>>> Then code is indented one level
line1
line2
</code></pre>
<p>Alternatively</p>
<pre><code>>>> doctest
fenced code works
always
</code></pre>
<h2 id="examples">Examples</h2>
<pre><code class="python">>>> nbytes(100)
'100.0 bytes'
line2
</code></pre>
<p>some text</p>
<p>some text</p>
<pre><code class="python">>>> another doctest
line1
line2
</code></pre>
<h2 id="example">Example</h2>
<pre><code class="python">>>> f()
Traceback (most recent call last):
...
Exception: something went wrong
</code></pre>'''
text = inspect.getdoc(self._docmodule.doctests)
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
def test_to_html(self):
text = '# Title\n\n`pdoc.Module` is a `Doc`, not `dict`.'
expected = ('<h1 id="title">Title</h1>\n'
'<p><a href="#pdoc.Module">Module</a> is a <a href="#pdoc.Doc">Doc</a>, '
'not <code>dict</code>.</p>')
module = pdoc.Module(pdoc)
def link(dobj, *args, **kwargs):
return '<a href="{}">{}</a>'.format(dobj.url(relative_to=module), dobj.qualname)
html = to_html(text, module=module, link=link)
self.assertEqual(html, expected)
self.assertIn('<a href=', to_html('`pdoc.Doc.url()`', module=module, link=link))
self.assertIn('<code>foo.f()</code>', to_html('`foo.f()`', module=module, link=link))
def test_latex_math(self):
expected = r'''<p>Inline equation: <span><span class="MathJax_Preview"> v_t *\frac{1}{2}* j_i + [a] < 3 </span><script type="math/tex"> v_t *\frac{1}{2}* j_i + [a] < 3 </script></span>.</p>
<p>Block equation: <span><span class="MathJax_Preview"> v_t *\frac{1}{2}* j_i + [a] < 3 </span><script type="math/tex; mode=display"> v_t *\frac{1}{2}* j_i + [a] < 3 </script></span></p>
<p>Block equation: <span><span class="MathJax_Preview"> v_t *\frac{1}{2}* j_i + [a] < 3 </span><script type="math/tex; mode=display"> v_t *\frac{1}{2}* j_i + [a] < 3 </script></span></p>
<p><span><span class="MathJax_Preview"> v_t *\frac{1}{2}* j_i + [a] < 3 </span><script type="math/tex; mode=display"> v_t *\frac{1}{2}* j_i + [a] < 3 </script></span></p>''' # noqa: E501
text = inspect.getdoc(self._docmodule.latex_math)
html = to_html(text, module=self._module, link=self._link, latex_math=True)
self.assertEqual(html, expected)
def test_doctests(self):
expected = '''<p>Need an intro paragrapgh.</p>
<pre><code>>>> Then code is indented one level
</code></pre>
<p>Alternatively</p>
<pre><code>fenced code works
</code></pre>'''
text = inspect.getdoc(self._docmodule.doctests)
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
def test_reST_include(self):
expected = '''<pre><code class="python"> x = 2
</code></pre>
<p>1
x = 2
x = 3
x =</p>'''
mod = pdoc.Module(pdoc.import_module(
os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE, '_reST_include', 'test.py')))
text = inspect.getdoc(mod.obj)
html = to_html(text, module=mod)
self.assertEqual(html, expected)
def test_numpy_curly_brace_expansion(self):
# See: https://github.com/mwaskom/seaborn/blob/66191d8a179f1bfa42f03749bc4a07e1c0c08156/seaborn/regression.py#L514 # noqa: 501
text = '''Parameters
----------
prefix_{x,y}_partial : str
some description
'''
expected = '''<h2 id="parameters">Parameters</h2>
<dl>
<dt><strong><code>prefix_{x,y}_partial</code></strong> : <code>str</code></dt>
<dd>some description</dd>
</dl>'''
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
def test_urls(self):
text = """Beautiful Soup
http://www.foo.bar
<https://foo.bar>
Work [like this](http://foo/) and [like that].
[like that]: ftp://bar
data:text/plain;base64,SGVsbG8sIFdvcmxkIQ%3D%3D"""
expected = """<p>Beautiful Soup
<a href="http://www.foo.bar">http://www.foo.bar</a>
<a href="https://foo.bar">https://foo.bar</a></p>
<p>Work <a href="http://foo/">like this</a> and <a href="ftp://bar">like that</a>.</p>
<p>data:text/plain;base64,SGVsbG8sIFdvcmxkIQ%3D%3D</p>"""
html = to_html(text)
self.assertEqual(html, expected)
def test_numpy(self):
expected = '''<p>Summary line.</p>
<h2 id="parameters">Parameters</h2>
<dl>
<dt><strong><code>x1</code></strong>, <strong><code>x2</code></strong> : <code>array_like</code></dt>
<dd>
<p>Input arrays,
description of <code>x1</code>, <code>x2</code>.</p>
<div class="admonition versionadded">
<p class="admonition-title">Added in version: 1.5.0</p>
</div>
</dd>
<dt><strong><code>x</code></strong> : { <code>NoneType</code>, <code>'B'</code>, <code>'C'</code> }, optional</dt>
<dd> </dd>
<dt><strong><code>n</code></strong> : <code>int</code> or <code>list</code> of <code>int</code></dt>
<dd>Description of num</dd>
<dt><strong><code>*args</code></strong>, <strong><code>**kwargs</code></strong></dt>
<dd>Passed on.</dd>
</dl>
<h2 id="returns">Returns</h2>
<dl>
<dt><strong><code>output</code></strong> : <a><code>pdoc.Doc</code></a></dt>
<dd>The output array</dd>
</dl>
<h2 id="raises">Raises</h2>
<dl>
<dt><strong><code>TypeError</code></strong></dt>
<dd>When something.</dd>
</dl>
<h2 id="see-also">See Also</h2>
<p><code>fromstring</code>, <code>loadtxt</code></p>
<h2 id="see-also_1">See Also</h2>
<dl>
<dt><a><code>pdoc.text</code></a></dt>
<dd>Function a with its description.</dd>
<dt><a><code>scipy.random.norm</code></a></dt>
<dd>Random variates, PDFs, etc.</dd>
</dl>
<h2 id="notes">Notes</h2>
<p>Foo bar.</p>
<h3 id="h3-title">H3 Title</h3>
<p>Foo bar.</p>''' # noqa: E501
text = inspect.getdoc(self._docmodule.numpy)
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
def test_reST_include(self):
expected = '''<pre><code class="python"> x = 2
</code></pre>
<p>1
x = 2
x = 3
x =</p>'''
mod = pdoc.Module(pdoc.import_module(
os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE, '_reST_include', 'test.py')))
text = inspect.getdoc(mod.obj)
html = to_html(text, module=mod)
self.assertEqual(html, expected)
# Ensure includes are resolved within docstrings already,
# e.g. for `pdoc.html_helpers.extract_toc()` to work
self.assertIn('Command-line interface',
pdoc.Module(pdoc).docstring)
def test_reST_directives(self):
expected = '''<div class="admonition todo">
<p class="admonition-title">TODO</p>
<p>Create something.</p>
</div>
<div class="admonition admonition">
<p class="admonition-title">Example</p>
<p>Image shows something.</p>
<p><img alt="" src="https://www.debian.org/logos/openlogo-nd-100.png"></p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Can only nest admonitions two levels.</p>
</div>
</div>
<p><img alt="" src="https://www.debian.org/logos/openlogo-nd-100.png"></p>
<p>Now you know.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Some warning
lines.</p>
</div>
<ul>
<li>
<p>Describe some func in a list
across multiple lines:</p>
<div class="admonition deprecated">
<p class="admonition-title">Deprecated since version: 3.1</p>
<p>Use <code>spam</code> instead.</p>
</div>
<div class="admonition versionadded">
<p class="admonition-title">Added in version: 2.5</p>
<p>The <em>spam</em> parameter.</p>
</div>
</li>
</ul>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p>Don't touch this!</p>
</div>'''
text = inspect.getdoc(self._docmodule.reST_directives)
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
def test_urls(self):
text = """Beautiful Soup
http://www.foo.bar
http://www.foo.bar?q="foo"
<a href="https://travis-ci.org/cs01/pygdbmi"><img src="https://foo" /></a>
<https://foo.bar>
Work [like this](http://foo/) and [like that].
[like that]: ftp://bar
data:text/plain;base64,SGVsbG8sIFdvcmxkIQ%3D%3D"""
expected = """<p>Beautiful Soup
<a href="http://www.foo.bar">http://www.foo.bar</a>
<a href="http://www.foo.bar?q="foo"">http://www.foo.bar?q="foo"</a>
<a href="https://travis-ci.org/cs01/pygdbmi"><img src="https://foo" /></a>
<a href="https://foo.bar">https://foo.bar</a></p>
<p>Work <a href="http://foo/">like this</a> and <a href="ftp://bar">like that</a>.</p>
<p>data:text/plain;base64,SGVsbG8sIFdvcmxkIQ%3D%3D</p>"""
html = to_html(text)
self.assertEqual(html, expected)
def test_google(self):
expected = '''<p>Summary line.
Nomatch:</p>
<h2 id="args">Args</h2>
<dl>
<dt><strong><code>arg1</code></strong> : <code>int</code></dt>
<dd>Description of arg1</dd>
<dt><strong><code>arg2</code></strong> : <code>str</code> or <code>int</code></dt>
<dd>Description of arg2</dd>
<dt><strong><code>*args</code></strong></dt>
<dd>passed around</dd>
</dl>
<h2 id="returns">Returns</h2>
<dl>
<dt><strong><code>bool</code></strong></dt>
<dd>Description of return value</dd>
</dl>
<h2 id="raises">Raises</h2>
<dl>
<dt><strong><code>AttributeError</code></strong></dt>
<dd>
<p>The <code>Raises</code> section is a list of all exceptions
that are relevant to the interface.</p>
<p>and a third line.</p>
</dd>
<dt><strong><code>ValueError</code></strong></dt>
<dd>If <code>arg2</code> is equal to <code>arg1</code>.</dd>
</dl>
<h2 id="examples">Examples</h2>
<p>Examples in doctest format.</p>
<pre><code>>>> a = [1,2,3]
</code></pre>
<h2 id="todos">Todos</h2>
<ul>
<li>For module TODOs</li>
</ul>'''
text = inspect.getdoc(self._docmodule.google)
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
def test_google(self):
expected = '''<p>Summary line.
Nomatch:</p>
<h2 id="args">Args</h2>
<dl>
<dt><strong><code>arg1</code></strong> : <code>str</code>, optional</dt>
<dd>Text1</dd>
<dt><strong><code>arg2</code></strong> : <code>List</code>[<code>str</code>], optional,\
default=<code>10</code></dt>
<dd>Text2</dd>
</dl>
<h2 id="args_1">Args</h2>
<dl>
<dt><strong><code>arg1</code></strong> : <code>int</code></dt>
<dd>Description of arg1</dd>
<dt><strong><code>arg2</code></strong> : <code>str</code> or <code>int</code></dt>
<dd>Description of arg2</dd>
<dt><strong><code>test_sequence</code></strong></dt>
<dd>
<p>2-dim numpy array of real numbers, size: N * D
- the test observation sequence.</p>
<pre><code>test_sequence =
code
</code></pre>
<p>Continue.</p>
</dd>
<dt><strong><code>*args</code></strong></dt>
<dd>passed around</dd>
</dl>
<h2 id="returns">Returns</h2>
<dl>
<dt><strong><code>issue_10</code></strong></dt>
<dd>description didn't work across multiple lines
if only a single item was listed. <code>inspect.cleandoc()</code>
somehow stripped the required extra indentation.</dd>
</dl>
<h2 id="raises">Raises</h2>
<dl>
<dt><strong><code>AttributeError</code></strong></dt>
<dd>
<p>The <code>Raises</code> section is a list of all exceptions
that are relevant to the interface.</p>
<p>and a third line.</p>
</dd>
<dt><strong><code>ValueError</code></strong></dt>
<dd>If <code>arg2</code> is equal to <code>arg1</code>.</dd>
</dl>
<p>Test a title without a blank line before it.</p>
<h2 id="args_2">Args</h2>
<dl>
<dt><strong><code>A</code></strong></dt>
<dd>a</dd>
</dl>
<h2 id="examples">Examples</h2>
<p>Examples in doctest format.</p>
<pre><code>>>> a = [1,2,3]
</code></pre>
<h2 id="todos">Todos</h2>
<ul>
<li>For module TODOs</li>
</ul>'''
text = inspect.getdoc(self._docmodule.google)
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
