

pydocmk2.document

pydocmk2.document

This module implements the structural representation of an API documentation
in separate documents and symbolic names. The final documentation is rendered
from this structured representation.

Modules

• os

Classes

• builtin.object
• • Document
  • Index
  • Section

class Document(builtin.object)

Represents a single document that may contain several #Section#s. Every
document *must* have a relative URL associated with it.

# Attributes
index (Index): The index that the document belongs to.
url (str): The relative URL of the document.

Methods

init(self, index, url)

Descriptors

dict

dictionary for instance variables (if defined)

weakref

list of weak references to the object (if defined)

class Index(builtin.object)

The index manages all documents and sections globally. It keeps track of
the symbolic names allocated for the sections to be able to link to them
from other sections.

# Attributes
documents (dict):
sections (dict):

Methods

init(self)

new_document(self, filename, url=None)

Create a new document.

# Arguments
filename (str): The filename of the document. Must end with `.md`.
url (str): The relative URL of the document. If omitted, will be
  automatically deduced from *filename* (same without the `.md` suffix).

# Raises
ValueError: If *filename* does not end with `.md`.
ValueError: If *filename* is not a relative path.
ValueError: If a document with the specified *filename* already exists.

new_section(self, doc, *args, **kwargs)

Create a new section in the specified document. The arguments for this
method match the parameters for the #Section constructor.

# Raises
ValueError: If the section identifier is already used.

Descriptors

dict

dictionary for instance variables (if defined)

weakref

list of weak references to the object (if defined)

class Section(builtin.object)

A section represents a part of a #Document. It contains Markdown-formatted
content that will be rendered into a file at some point.

# Attributes
doc (Document): The document that the section belongs to.
identifier (str, None): The globally unique identifier of the section. This
  identifier usually matches the name of the element that the section
  describes (eg. a class or function) and will be used for cross-referencing.
title (str, None): The title of the section. If specified, it will be
  rendered before `section.content` and the header-size will depend on
  the `section.depth`.
depth (int): The depth of the section, defaults to 1. Currently only affects
  the header-size that is rendered for the `section.title`.
content (str): The Markdown-formatted content of the section.

Methods

init(self, doc, identifier=None, title=None, depth=1, content=None, header_type='html', pre_dir=None, post_dir=None)

render(self, stream)

Render the section into *stream*.

Descriptors

dict

dictionary for instance variables (if defined)

weakref

list of weak references to the object (if defined)

index

Returns the #Index that this section is associated with, accessed via
`section.document`.

Section

pydocmk2.document.Section = class Section(__builtin__.object)

A section represents a part of a #Document. It contains Markdown-formatted
content that will be rendered into a file at some point.

# Attributes
doc (Document): The document that the section belongs to.
identifier (str, None): The globally unique identifier of the section. This
  identifier usually matches the name of the element that the section
  describes (eg. a class or function) and will be used for cross-referencing.
title (str, None): The title of the section. If specified, it will be
  rendered before `section.content` and the header-size will depend on
  the `section.depth`.
depth (int): The depth of the section, defaults to 1. Currently only affects
  the header-size that is rendered for the `section.title`.
content (str): The Markdown-formatted content of the section.

Methods

__init__(self, doc, identifier=None, title=None, depth=1, content=None, header_type='html', pre_dir=None, post_dir=None)

render(self, stream)

Render the section into *stream*.

Descriptors

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

index

Returns the #Index that this section is associated with, accessed via
`section.document`.

index

pydocmk2.document.Section.index

Returns the #Index that this section is associated with, accessed via
`section.document`.

render

pydocmk2.document.Section.render = render(self, stream) unbound pydocmk2.document.Section method

Render the section into *stream*.

Document

pydocmk2.document.Document = class Document(__builtin__.object)

Represents a single document that may contain several #Section#s. Every
document *must* have a relative URL associated with it.

# Attributes
index (Index): The index that the document belongs to.
url (str): The relative URL of the document.

Methods

__init__(self, index, url)

Descriptors

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

Index

pydocmk2.document.Index = class Index(__builtin__.object)

The index manages all documents and sections globally. It keeps track of
the symbolic names allocated for the sections to be able to link to them
from other sections.

# Attributes
documents (dict):
sections (dict):

Methods

__init__(self)

new_document(self, filename, url=None)

Create a new document.

# Arguments
filename (str): The filename of the document. Must end with `.md`.
url (str): The relative URL of the document. If omitted, will be
  automatically deduced from *filename* (same without the `.md` suffix).

# Raises
ValueError: If *filename* does not end with `.md`.
ValueError: If *filename* is not a relative path.
ValueError: If a document with the specified *filename* already exists.

new_section(self, doc, *args, **kwargs)

Create a new section in the specified document. The arguments for this
method match the parameters for the #Section constructor.

# Raises
ValueError: If the section identifier is already used.

Descriptors

__dict__

dictionary for instance variables (if defined)

__weakref__

list of weak references to the object (if defined)

new_document

pydocmk2.document.Index.new_document = new_document(self, filename, url=None) unbound pydocmk2.document.Index method

Create a new document.

# Arguments
filename (str): The filename of the document. Must end with `.md`.
url (str): The relative URL of the document. If omitted, will be
  automatically deduced from *filename* (same without the `.md` suffix).

# Raises
ValueError: If *filename* does not end with `.md`.
ValueError: If *filename* is not a relative path.
ValueError: If a document with the specified *filename* already exists.

new_section

pydocmk2.document.Index.new_section = new_section(self, doc, *args, **kwargs) unbound pydocmk2.document.Index method

Create a new section in the specified document. The arguments for this
method match the parameters for the #Section constructor.

# Raises
ValueError: If the section identifier is already used.