Package epydoc :: Module apidoc :: Class NamespaceDoc

[hide private]
[frames] | no frames]

# Class NamespaceDoc

source code

API documentation information about a singe Python namespace value. (I.e., a module or a class).

Instance Methods | [hide private]

__init__(self, **kwargs) Construct a new `APIDoc` object. | source code call graph

Call Graph

`bool`

is_detailed(self) Does this object deserve a box with extra details? | source code call graph

Call Graph

apidoc_links(self, **filters) Return a list of all `APIDoc`s that are directly linked from this `APIDoc` (i.e., are contained or pointed to by one or more of this `APIDoc`'s attributes.) | source code call graph

Call Graph

init_sorted_variables(self) Initialize the sorted_variables attribute, based on the variables and sort_spec attributes. | source code call graph

Call Graph

init_variable_groups(self) Initialize the variable_groups attribute, based on the sorted_variables and group_specs attributes. | source code call graph

Call Graph

group_names(self) Return a list of the group names defined by this namespace, in the order in which they should be listed, with no duplicates. | source code call graph

Call Graph

_init_grouping(self, elts) Divide a given a list of APIDoc objects into groups, as specified by self.group_specs. | source code call graph

Call Graph

report_unused_groups(self) Issue a warning for any @group items that were not used by _init_grouping(). | source code call graph

Call Graph

Inherited from `ValueDoc`: `__getstate__`, `__repr__`, `__setstate__` Inherited from `APIDoc`: `__cmp__`, `__hash__`, `__setattr__`, `__str__`, `merge_and_overwrite`, `pp`, `specialize_to` Inherited from `APIDoc` (private): `_debug_setattr` Inherited from `object`: `__delattr__`, `__getattribute__`, `__new__`, `__reduce__`, `__reduce_ex__`
Value Representation
Inherited from `ValueDoc`: `pyval_repr`, `summary_pyval_repr`

Class Variables | [hide private]

Value Representation
Inherited from `ValueDoc`: `REPR_LINELEN`, `REPR_MAXLINES`, `REPR_MIN_SCORE`, `SUMMARY_REPR_LINELEN`

Instance Variables | [hide private]

Inherited from `ValueDoc`: `canonical_name`, `toktree`
Information about Variables
`dict` from `string` to VariableDoc | variables = `_Sentinel('UNKNOWN')` The contents of the namespace, encoded as a dictionary mapping from identifiers to `VariableDoc`s.
`list` of VariableDoc | sorted_variables = `_Sentinel('UNKNOWN')` A list of all variables defined by this namespace, in sorted order.
`list` of `str` | sort_spec = `_Sentinel('UNKNOWN')` The order in which variables should be listed, encoded as a list of names.
`list` of `(str,list)` | group_specs = `_Sentinel('UNKNOWN')` The groups that are defined by this namespace's docstrings.
`dict` from `str` to `list` of VariableDoc | variable_groups = `_Sentinel('UNKNOWN')` A dictionary specifying what group each variable belongs to.
Value Representation
Inherited from `ValueDoc`: `parse_repr`, `pyval`
Context
Inherited from `ValueDoc`: `defining_module`
Information about Imported Variables
Inherited from `ValueDoc`: `proxy_for`
Docstrings
Inherited from `APIDoc`: `docstring`, `docstring_lineno`
Information Extracted from Docstrings
Inherited from `APIDoc`: `descr`, `extra_docstring_fields`, `metadata`, `other_docs`, `summary`
Source Information
Inherited from `APIDoc`: `docs_extracted_by`

Properties | [hide private]

Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, **kwargs)
(Constructor)

source code
call graph

Call Graph

Construct a new `APIDoc` object. Keyword arguments may be used to initialize the new `APIDoc`'s attributes.

Raises:
  - `TypeError` - If a keyword argument is specified that does not correspond to a valid attribute for this (sub)class of `APIDoc`.
Overrides: object.__init__
  (inherited documentation)

### is_detailed(self)

source code
call graph

Call Graph

Does this object deserve a box with extra details?

Returns: `bool`
  True if the object needs extra details, else False.
Overrides: APIDoc.is_detailed
  (inherited documentation)

### apidoc_links(self, **filters)

source code
call graph

Call Graph

Return a list of all `APIDoc`s that are directly linked from this `APIDoc` (i.e., are contained or pointed to by one or more of this `APIDoc`'s attributes.)

Keyword argument `filters` can be used to selectively exclude certain categories of attribute value. For example, using `includes=False` will exclude variables that were imported from other modules; and `subclasses=False` will exclude subclasses. The filter categories currently supported by epydoc are:

- `imports`: Imported variables.
- `packages`: Containing packages for modules.
- `submodules`: Contained submodules for packages.
- `bases`: Bases for classes.
- `subclasses`: Subclasses for classes.
- `variables`: All variables.
- `private`: Private variables.
- `overrides`: Points from class variables to the variables they override. This filter is False by default.

Overrides: APIDoc.apidoc_links
  (inherited documentation)

### init_sorted_variables(self)

source code
call graph

Call Graph

Initialize the sorted_variables attribute, based on the variables and sort_spec attributes. This should usually be called after all variables have been added to `variables` (including any inherited variables for classes).

### _init_grouping(self, elts)

source code
call graph

Call Graph

Divide a given a list of APIDoc objects into groups, as specified by self.group_specs.

Parameters:
  - `elts` - A list of tuples `(name, apidoc)`.
Returns:
  A list of tuples `(groupname, elts)`, where `groupname` is the name of a group and `elts` is a list of `APIDoc`s in that group. The first tuple has name `''`, and is used for ungrouped elements. The remaining tuples are listed in the order that they appear in `self.group_specs`. Within each tuple, the elements are listed in the order that they appear in `api_docs`.

Instance Variable Details | [hide private]

### variables

The contents of the namespace, encoded as a dictionary mapping from identifiers to `VariableDoc`s. This dictionary contains all names defined by the namespace, including imported variables, aliased variables, and variables inherited from base classes (once inherit_docs() has added them).

Type:
  `dict` from `string` to VariableDoc

Value:

      _Sentinel('UNKNOWN')

### sorted_variables

A list of all variables defined by this namespace, in sorted order. The elements of this list should exactly match the values of variables. The sort order for this list is defined as follows:

- Any variables listed in a `@sort` docstring field are listed in the order given by that field.
- These are followed by any variables that were found while parsing the source code, in the order in which they were defined in the source file.
- Finally, any remaining variables are listed in alphabetical order.

Type:
  `list` of VariableDoc

Value:

      _Sentinel('UNKNOWN')

### sort_spec

The order in which variables should be listed, encoded as a list of names. Any variables whose names are not included in this list should be listed alphabetically, following the variables that are included.

Type:
  `list` of `str`

Value:

      _Sentinel('UNKNOWN')

### group_specs

The groups that are defined by this namespace's docstrings. `group_specs` is encoded as an ordered list of tuples `(group_name, elt_names)`, where `group_name` is the

name of a group and `elt_names` is a list of element names in that group. (An element can be a variable or a submodule.) A '*' in an element name will match any string of characters.

Type:
  `list` of `(str,list)`

Value:

      _Sentinel('UNKNOWN')

### variable_groups

A dictionary specifying what group each variable belongs to. The keys of the dictionary are group names, and the values are lists of `VariableDoc`s. The order that groups should be listed in should be taken from group_specs.

Type:
  `dict` from `str` to `list` of VariableDoc

Value:

      _Sentinel('UNKNOWN')