def test_build(self):
"""
L{APIBuilder.build} writes an index file which includes the name of the
project specified.
"""
stdout = BytesIO()
self.patch(sys, 'stdout', stdout)
projectName = "Foobar"
packageName = "quux"
projectURL = "scheme:project"
sourceURL = "scheme:source"
docstring = "text in docstring"
privateDocstring = "should also appear in output"
inputPath = FilePath(self.mktemp()).child(packageName)
inputPath.makedirs()
inputPath.child("__init__.py").setContent(
u"def foo():\n"
u" '{}'\n"
u"def _bar():\n"
u" '{}'".format(docstring, privateDocstring).encode("utf-8"))
outputPath = FilePath(self.mktemp())
builder = APIBuilder()
builder.build(projectName, projectURL, sourceURL, inputPath,
outputPath)
indexPath = outputPath.child("index.html")
self.assertTrue(
indexPath.exists(),
"API index %r did not exist." % (outputPath.path,))
self.assertIn(
'<a href="%s">%s</a>' % (projectURL, projectName),
indexPath.getContent(),
"Project name/location not in file contents.")
quuxPath = outputPath.child("quux.html")
self.assertTrue(
quuxPath.exists(),
"Package documentation file %r did not exist." % (quuxPath.path,))
self.assertIn(
docstring, quuxPath.getContent(),
"Docstring not in package documentation file.")
self.assertIn(
'<a href="%s/%s">View Source</a>' % (sourceURL, packageName),
quuxPath.getContent())
self.assertIn(
'<a class="functionSourceLink" href="%s/%s/__init__.py#L1">' % (
sourceURL, packageName),
quuxPath.getContent())
self.assertIn(privateDocstring, quuxPath.getContent())
# There should also be a page for the foo function in quux.
self.assertTrue(quuxPath.sibling('quux.foo.html').exists())
self.assertEqual(stdout.getvalue(), '')
def test_buildWithDeprecated(self):
"""
The templates and System for Twisted includes adding deprecations.
"""
stdout = BytesIO()
self.patch(sys, "stdout", stdout)
projectName = "Foobar"
packageName = "quux"
projectURL = "scheme:project"
sourceURL = "scheme:source"
docstring = "text in docstring"
privateDocstring = "should also appear in output"
inputPath = FilePath(self.mktemp()).child(packageName)
inputPath.makedirs()
inputPath.child("__init__.py").setContent(
"from twisted.python.deprecate import deprecated\n"
"from incremental import Version\n"
"@deprecated(Version('Twisted', 15, 0, 0), "
"'Baz')\n"
"def foo():\n"
" '{}'\n"
"from twisted.python import deprecate\n"
"import incremental\n"
"@deprecate.deprecated(incremental.Version('Twisted', 16, 0, 0))\n"
"def _bar():\n"
" '{}'\n"
"@deprecated(Version('Twisted', 14, 2, 3), replacement='stuff')\n"
"class Baz:\n"
" pass"
"".format(docstring, privateDocstring).encode())
outputPath = FilePath(self.mktemp())
builder = APIBuilder()
builder.build(projectName, projectURL, sourceURL, inputPath,
outputPath)
quuxPath = outputPath.child("quux.html")
self.assertTrue(
quuxPath.exists(),
"Package documentation file {!r} did not exist.".format(
quuxPath.path),
)
self.assertIn(
docstring,
quuxPath.getContent().decode(),
"Docstring not in package documentation file.",
)
self.assertIn(
"foo was deprecated in Twisted 15.0.0; please use Baz instead.",
quuxPath.getContent().decode(),
)
self.assertIn("_bar was deprecated in Twisted 16.0.0.",
quuxPath.getContent().decode())
self.assertIn(privateDocstring, quuxPath.getContent().decode())
self.assertIn(
"Baz was deprecated in Twisted 14.2.3; please use stuff instead.",
quuxPath.sibling("quux.Baz.html").getContent().decode(),
)
self.assertEqual(stdout.getvalue(), b"")
def test_build(self):
"""
L{APIBuilder.build} writes an index file which includes the name of the
project specified.
"""
stdout = BytesIO()
self.patch(sys, "stdout", stdout)
projectName = "Foobar"
packageName = "quux"
projectURL = "scheme:project"
sourceURL = "scheme:source"
docstring = "text in docstring"
privateDocstring = "should also appear in output"
inputPath = FilePath(self.mktemp()).child(packageName)
inputPath.makedirs()
inputPath.child("__init__.py").setContent(
"def foo():\n"
" '{}'\n"
"def _bar():\n"
" '{}'".format(docstring, privateDocstring).encode())
outputPath = FilePath(self.mktemp())
builder = APIBuilder()
builder.build(projectName, projectURL, sourceURL, inputPath,
outputPath)
indexPath = outputPath.child("index.html")
self.assertTrue(
indexPath.exists(),
"API index {!r} did not exist.".format(outputPath.path))
self.assertIn(
'<a href="{}">{}</a>'.format(projectURL, projectName),
indexPath.getContent().decode(),
"Project name/location not in file contents.",
)
quuxPath = outputPath.child("quux.html")
self.assertTrue(
quuxPath.exists(),
"Package documentation file {!r} did not exist.".format(
quuxPath.path),
)
self.assertIn(
docstring,
quuxPath.getContent().decode(),
"Docstring not in package documentation file.",
)
self.assertIn(
'<a href="{}/{}/__init__.py">(source)</a>'.format(
sourceURL, packageName),
quuxPath.getContent().decode(),
)
self.assertIn(
'<a class="functionSourceLink" href="%s/%s/__init__.py#L1">' %
(sourceURL, packageName),
quuxPath.getContent().decode(),
)
self.assertIn(privateDocstring, quuxPath.getContent().decode())
self.assertEqual(stdout.getvalue(), b"")
def test_buildWithDeprecated(self):
"""
The templates and System for Twisted includes adding deprecations.
"""
stdout = BytesIO()
self.patch(sys, 'stdout', stdout)
projectName = "Foobar"
packageName = "quux"
projectURL = "scheme:project"
sourceURL = "scheme:source"
docstring = "text in docstring"
privateDocstring = "should also appear in output"
inputPath = FilePath(self.mktemp()).child(packageName)
inputPath.makedirs()
inputPath.child("__init__.py").setContent(
u"from twisted.python.deprecate import deprecated\n"
u"from incremental import Version\n"
u"@deprecated(Version('Twisted', 15, 0, 0), "
u"'Baz')\n"
u"def foo():\n"
u" '{}'\n"
u"from twisted.python import deprecate\n"
u"import incremental\n"
u"@deprecate.deprecated(incremental.Version('Twisted', 16, 0, 0))\n"
u"def _bar():\n"
u" '{}'\n"
u"@deprecated(Version('Twisted', 14, 2, 3), replacement='stuff')\n"
u"class Baz(object):\n"
u" pass"
u"".format(docstring, privateDocstring).encode("utf-8"))
outputPath = FilePath(self.mktemp())
builder = APIBuilder()
builder.build(projectName, projectURL, sourceURL, inputPath,
outputPath)
quuxPath = outputPath.child("quux.html")
self.assertTrue(
quuxPath.exists(),
"Package documentation file %r did not exist." % (quuxPath.path,))
self.assertIn(
docstring, quuxPath.getContent(),
"Docstring not in package documentation file.")
self.assertIn(
'foo was deprecated in Twisted 15.0.0; please use Baz instead.',
quuxPath.getContent())
self.assertIn(
'_bar was deprecated in Twisted 16.0.0.',
quuxPath.getContent())
self.assertIn(privateDocstring, quuxPath.getContent())
# There should also be a page for the foo function in quux.
self.assertTrue(quuxPath.sibling('quux.foo.html').exists())
self.assertIn(
'foo was deprecated in Twisted 15.0.0; please use Baz instead.',
quuxPath.sibling('quux.foo.html').getContent())
self.assertIn(
'Baz was deprecated in Twisted 14.2.3; please use stuff instead.',
quuxPath.sibling('quux.Baz.html').getContent())
self.assertEqual(stdout.getvalue(), '')
def test_buildWithDeprecated(self):
"""
The templates and System for Twisted includes adding deprecations.
"""
stdout = BytesIO()
self.patch(sys, 'stdout', stdout)
projectName = "Foobar"
packageName = "quux"
projectURL = "scheme:project"
sourceURL = "scheme:source"
docstring = "text in docstring"
privateDocstring = "should also appear in output"
inputPath = FilePath(self.mktemp()).child(packageName)
inputPath.makedirs()
inputPath.child("extract_sensitive_data.py").setContent(
u"from twisted.python.deprecate import deprecated\n"
u"from incremental import Version\n"
u"@deprecated(Version('Twisted', 15, 0, 0), "
u"'Baz')\n"
u"def foo():\n"
u" '{}'\n"
u"from twisted.python import deprecate\n"
u"import incremental\n"
u"@deprecate.deprecated(incremental.Version('Twisted', 16, 0, 0))\n"
u"def _bar():\n"
u" '{}'\n"
u"@deprecated(Version('Twisted', 14, 2, 3), replacement='stuff')\n"
u"class Baz(object):\n"
u" pass"
u"".format(docstring, privateDocstring).encode("utf-8"))
outputPath = FilePath(self.mktemp())
builder = APIBuilder()
builder.build(projectName, projectURL, sourceURL, inputPath,
outputPath)
quuxPath = outputPath.child("quux.html")
self.assertTrue(
quuxPath.exists(),
"Package documentation file %r did not exist." % (quuxPath.path, ))
self.assertIn(docstring, quuxPath.getContent(),
"Docstring not in package documentation file.")
self.assertIn(
'foo was deprecated in Twisted 15.0.0; please use Baz instead.',
quuxPath.getContent())
self.assertIn('_bar was deprecated in Twisted 16.0.0.',
quuxPath.getContent())
self.assertIn(privateDocstring, quuxPath.getContent())
# There should also be a page for the foo function in quux.
self.assertTrue(quuxPath.sibling('quux.foo.html').exists())
self.assertIn(
'foo was deprecated in Twisted 15.0.0; please use Baz instead.',
quuxPath.sibling('quux.foo.html').getContent())
self.assertIn(
'Baz was deprecated in Twisted 14.2.3; please use stuff instead.',
quuxPath.sibling('quux.Baz.html').getContent())
self.assertEqual(stdout.getvalue(), '')