pydoctor.test.test_epydoc2stan

module documentation

Undocumented

Class ​In​Memory​Inventory A simple inventory implementation which has an in-memory API link mapping.
Class ​Recording​Annotation​Linker A DocstringLinker implementation that cannot find any links, but does record which identifiers it was asked to link.
Function docstring2html Undocumented
Function summary2html Undocumented
Function test​_annotation​_formatting Perform two checks on the annotation formatting:
Function test​_constant​_values​_rst Test epydoc2stan.format_constant_value().
Function test​_constructor​_param​_on​_class Constructor parameters can be documented on the class.
Function test_​Epydoc​Linker_look_for_intersphinx_hit Return the link from inventory based on first package name.
Function test_​Epydoc​Linker_look_for_intersphinx_no_link Return None if inventory had no link for our markup.
Function test_​Epydoc​Linker_resolve_identifier_xref_internal_full_name Link to an internal object referenced by its full name.
Function test_​Epydoc​Linker_resolve_identifier_xref_intersphinx_absolute_id Returns the link from Sphinx inventory based on a cross reference ID specified in absolute dotted path and with a custom pretty text for the URL.
Function test_​Epydoc​Linker_resolve_identifier_xref_intersphinx_link_not_found No summary
Function test_​Epydoc​Linker_resolve_identifier_xref_intersphinx_relative_id Return the link from inventory using short names, by resolving them based on the imports done in the module.
Function test_​Epydoc​Linker_resolve_identifier_xref_order Check that the best match is picked when there are multiple candidates.
Function test​_func​_arg​_and​_ret​_annotation Undocumented
Function test​_func​_arg​_and​_ret​_annotation​_with​_override Undocumented
Function test​_func​_arg​_not​_inherited Do not warn when a subclass method lacks parameters that are documented in an inherited docstring.
Function test​_func​_arg​_when​_doc​_missing Undocumented
Function test​_func​_missing​_param​_name Param and type fields must include the name of the parameter.
Function test​_func​_no​_such​_arg Warn about documented parameters that don't exist in the definition.
Function test​_func​_no​_such​_arg​_warn​_once Warn exactly once about a param/type combination not existing.
Function test​_func​_param​_as​_keyword Warn when a parameter is documented as a @keyword.
Function test​_func​_param​_duplicate Warn when the same parameter is documented more than once.
Function test​_func​_raise​_linked Raise fields are formatted by linking the exception type.
Function test​_func​_raise​_missing​_exception​_type When a raise field is missing the exception type, a warning is logged and the HTML will list the exception type as unknown.
Function test​_func​_starargs Var-args can be named in fields with or without asterixes. Constructor parameters can be documented on the class.
Function test​_func​_starargs​_more Star arguments, even if there are not named 'args' or 'kwargs', are recognized.
Function test​_func​_starargs​_no​_docstring Star arguments, even if there are not docstring attached, will be rendered with stars.
Function test​_func​_undocumented​_return​_nothing When the returned value is undocumented (no 'return' field) and its type annotation is None, omit the "Returns" entry from the output.
Function test​_func​_undocumented​_return​_something When the returned value is undocumented (no 'return' field) and its type annotation is not None, include the "Returns" entry in the output.
Function test​_html​_empty​_module Undocumented
Function test​_inline​_field​_name Warn if a name is given for a type field in a variable docstring. A variable docstring only documents a single variable, so the name is redundant at best and misleading at worst.
Function test​_inline​_field​_type The type field in a variable docstring updates the parsed_type of the Attribute it documents.
Function test​_ivar​_overriding​_attribute An 'ivar' field in a subclass overrides a docstring for the same attribute set in the base class.
Function test​_missing​_field​_name Undocumented
Function test​_missing​_param​_computed​_base Do not warn if a parameter might be added by a computed base class.
Function test​_module​_docformat Test if Module.docformat effectively override System.options.docformat
Function test​_module​_docformat​_inheritence Undocumented
Function test​_module​_docformat​_with​_docstring​_inheritence Undocumented
Function test​_multiple​_types Undocumented
Function test​_summary Undocumented
Function test​_unexpected​_field​_args Warn when field arguments that should be empty aren't.
Function test​_unknown​_field​_name Undocumented
Function test​_warns​_field Test if the :warns: field is correctly recognized.
Function test​_xref​_link​_intersphinx A linked name that is documented in another project is linked using an absolute URL (retrieved via Intersphinx).
Function test​_xref​_link​_not​_found A linked name that is not found is output as text.
Function test​_xref​_link​_other​_page A linked name that is documented on a different page but within the same project is linked using a relative URL.
Function test​_xref​_link​_same​_page A linked name that is documented on the same page is linked using only a fragment as the URL.
Function test​_xref​_not​_found​_epytext When a link in an epytext docstring cannot be resolved, the reference and the line number of the link should be reported.
Function test​_xref​_not​_found​_restructured No summary
Function test​_yields​_field Test if the :warns: field is correctly recognized.
def docstring2html(obj, docformat=None):

Undocumented

Parameters
obj:model.DocumentableUndocumented
docformat:Optional[str]Undocumented
Returns
strUndocumented
def summary2html(obj):

Undocumented

Parameters
obj:model.DocumentableUndocumented
Returns
strUndocumented
@mark.parametrize('annotation', ('<bool>', '<NotImplemented>', '<typing.Iterable>[<int>]', '<Literal>[<True>]', '<Mapping>[<str>, <C>]', '<Tuple>[<a.b.C>, <int>]', '<Tuple>[<a.b.C>, ...]', '<Callable>[[<str>, <bool>], <None>]'))
def test_annotation_formatting(annotation):

Perform two checks on the annotation formatting:

  • all type names in the annotation are passed to the linker
  • the plain text version of the output matches the input
Parameters
annotation:strUndocumented
Note
The annotation formatting is now handled by PyvalColorizer. We use the function flatten_text in order to back reproduce the original text annotations.
def test_constant_values_rst(capsys):
Test epydoc2stan.format_constant_value().
Parameters
capsys:CapSysUndocumented
def test_constructor_param_on_class(capsys):
Constructor parameters can be documented on the class.
Parameters
capsys:CapSysUndocumented
def test_EpydocLinker_look_for_intersphinx_hit():
Return the link from inventory based on first package name.
def test_EpydocLinker_look_for_intersphinx_no_link():
Return None if inventory had no link for our markup.
def test_EpydocLinker_resolve_identifier_xref_internal_full_name():
Link to an internal object referenced by its full name.
def test_EpydocLinker_resolve_identifier_xref_intersphinx_absolute_id():
Returns the link from Sphinx inventory based on a cross reference ID specified in absolute dotted path and with a custom pretty text for the URL.
def test_EpydocLinker_resolve_identifier_xref_intersphinx_link_not_found(capsys):
A message is sent to stdout when no link could be found for the reference, while returning the reference name without an A link tag. The message contains the full name under which the reference was resolved. FIXME: Use a proper logging system instead of capturing stdout. https://github.com/twisted/pydoctor/issues/112
Parameters
capsys:CapSysUndocumented
def test_EpydocLinker_resolve_identifier_xref_intersphinx_relative_id():
Return the link from inventory using short names, by resolving them based on the imports done in the module.
def test_EpydocLinker_resolve_identifier_xref_order(capsys):
Check that the best match is picked when there are multiple candidates.
Parameters
capsys:CapSysUndocumented
@pytest.mark.xfail
def test_func_arg_and_ret_annotation():

Undocumented

@pytest.mark.xfail
def test_func_arg_and_ret_annotation_with_override():

Undocumented

def test_func_arg_not_inherited(capsys):
Do not warn when a subclass method lacks parameters that are documented in an inherited docstring.
Parameters
capsys:CapSysUndocumented
@pytest.mark.xfail
def test_func_arg_when_doc_missing():

Undocumented

def test_func_missing_param_name(capsys):
Param and type fields must include the name of the parameter.
Parameters
capsys:CapSysUndocumented
@mark.parametrize('field', ('param', 'type'))
def test_func_no_such_arg(field, capsys):
Warn about documented parameters that don't exist in the definition.
Parameters
field:strUndocumented
capsys:CapSysUndocumented
def test_func_no_such_arg_warn_once(capsys):
Warn exactly once about a param/type combination not existing.
Parameters
capsys:CapSysUndocumented
def test_func_param_as_keyword(capsys):
Warn when a parameter is documented as a @keyword.
Parameters
capsys:CapSysUndocumented
def test_func_param_duplicate(capsys):
Warn when the same parameter is documented more than once.
Parameters
capsys:CapSysUndocumented
def test_func_raise_linked():
Raise fields are formatted by linking the exception type.
def test_func_raise_missing_exception_type(capsys):
When a raise field is missing the exception type, a warning is logged and the HTML will list the exception type as unknown.
Parameters
capsys:CapSysUndocumented
def test_func_starargs(capsys):
Var-args can be named in fields with or without asterixes. Constructor parameters can be documented on the class.
Parameters
capsys:CapSysUndocumented
Note
Asterixes need to be escaped with reStructuredText.
def test_func_starargs_more(capsys):
Star arguments, even if there are not named 'args' or 'kwargs', are recognized.
Parameters
capsys:CapSysUndocumented
def test_func_starargs_no_docstring(capsys):
Star arguments, even if there are not docstring attached, will be rendered with stars.
Parameters
capsys:CapSysUndocumented
Note
This test might not pass anymore when we include the annotations inside the signatures.
def test_func_undocumented_return_nothing():
When the returned value is undocumented (no 'return' field) and its type annotation is None, omit the "Returns" entry from the output.
def test_func_undocumented_return_something():
When the returned value is undocumented (no 'return' field) and its type annotation is not None, include the "Returns" entry in the output.
def test_html_empty_module():

Undocumented

def test_inline_field_name(capsys):
Warn if a name is given for a type field in a variable docstring. A variable docstring only documents a single variable, so the name is redundant at best and misleading at worst.
Parameters
capsys:CapSysUndocumented
def test_inline_field_type(capsys):
The type field in a variable docstring updates the parsed_type of the Attribute it documents.
Parameters
capsys:CapSysUndocumented
def test_ivar_overriding_attribute():

An 'ivar' field in a subclass overrides a docstring for the same attribute set in the base class.

The 'a' attribute in the test code reproduces a regression introduced in pydoctor 20.7.0, where the summary would be constructed from the base class documentation instead. The problem was in the fact that a split field's docstring is stored in 'parsed_docstring', while format_summary() looked there only if no unparsed docstring could be found.

The 'b' attribute in the test code is there to make sure that in the absence of an 'ivar' field, the docstring is inherited.

def test_missing_field_name(capsys):

Undocumented

Parameters
capsys:CapSysUndocumented
def test_missing_param_computed_base(capsys):
Do not warn if a parameter might be added by a computed base class.
Parameters
capsys:CapSysUndocumented
def test_module_docformat(capsys):
Test if Module.docformat effectively override System.options.docformat
Parameters
capsys:CapSysUndocumented
def test_module_docformat_inheritence(capsys):

Undocumented

Parameters
capsys:CapSysUndocumented
def test_module_docformat_with_docstring_inheritence(capsys):

Undocumented

Parameters
capsys:CapSysUndocumented
def test_multiple_types():

Undocumented

def test_summary():

Undocumented

def test_unexpected_field_args(capsys):
Warn when field arguments that should be empty aren't.
Parameters
capsys:CapSysUndocumented
def test_unknown_field_name(capsys):

Undocumented

Parameters
capsys:CapSysUndocumented
def test_warns_field(capsys):
Test if the :warns: field is correctly recognized.
Parameters
capsys:CapSysUndocumented
def test_xref_link_intersphinx():
A linked name that is documented in another project is linked using an absolute URL (retrieved via Intersphinx).
def test_xref_link_not_found():
A linked name that is not found is output as text.
def test_xref_link_other_page():
A linked name that is documented on a different page but within the same project is linked using a relative URL.
def test_xref_link_same_page():
A linked name that is documented on the same page is linked using only a fragment as the URL.
def test_xref_not_found_epytext(capsys):
When a link in an epytext docstring cannot be resolved, the reference and the line number of the link should be reported.
Parameters
capsys:CapSysUndocumented
def test_xref_not_found_restructured(capsys):
When a link in an reStructedText docstring cannot be resolved, the reference and the line number of the link should be reported. However, currently the best we can do is report the starting line of the docstring instead.
Parameters
capsys:CapSysUndocumented
def test_yields_field(capsys):
Test if the :warns: field is correctly recognized.
Parameters
capsys:CapSysUndocumented