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)