doorstop.core.publisher.publish() - Code Metrics - jacebrowning/doorstop - Measure and Improve Code Quality continuously with Scrutinizer

doorstop.core.publisher.publish() F
last analyzed 2019-08-12 00:16 UTC

↳ Parent: doorstop.core.publisher

Complexity

Conditions

Size

Total Lines	76
Code Lines	39

Duplication

Lines	0
Ratio	0 %

Code Coverage

Tests	38
CRAP Score	14.0245

Importance

Changes

Metric	Value
eloc	39
dl	0
loc	76
rs	3.6
c	0
b	0
f	0
ccs	38
cts	40
cp	0.95
cc	14
nop	8
crap	14.0245

How to fix Long Method Complexity Many Parameters

Long Method

Small methods make your code easier to understand, in particular if combined with a good name. Besides, if your method is small, finding a good name is usually much easier.

For example, if you find yourself adding comments to a method's body, this is usually a good sign to extract the commented part to a new method, and use the comment as a starting point when coming up with a good name for this new method.

Commonly applied refactorings include:

If many parameters/temporary variables are present:
- Replace temporary variables with Query
- Introduce parameter object; often combined with preserve whole object
- If the above two are insufficient: Replace method with method object
If you have long conditionals: Decompose Conditional
Otherwise: Extract method

Complexity

Complex classes like doorstop.core.publisher.publish() often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes.

Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.

Many Parameters

Methods with many parameters are not only hard to understand, but their parameters also often become inconsistent when you need more, or different data.

There are several approaches to avoid long parameter lists:

If you can get the data from another object that the method knows about already: Replace the parameter with method call
If several parameters are part of another object: Preserve Whole Object
If parameters are not yet connected: Introduce Parameter Object

# SPDX-License-Identifier: LGPL-3.0-only

"""Functions to publish documents and items."""

import os
import tempfile
import textwrap

import bottle
import markdown
from bottle import template as bottle_template

from plantuml_markdown import PlantUMLMarkdownExtension

from doorstop import common, settings
from doorstop.common import DoorstopError
from doorstop.core import Document
from doorstop.core.types import is_item, is_tree, iter_documents, iter_items

EXTENSIONS = (
    'markdown.extensions.extra',
    'markdown.extensions.sane_lists',
    'mdx_outline',
    'mdx_math',
    PlantUMLMarkdownExtension(
        server='http://www.plantuml.com/plantuml',
        cachedir=tempfile.gettempdir(),
        format='svg',
        classes='class1,class2',
        title='UML',
        alt='UML Diagram',
    ),
)
CSS = os.path.join(os.path.dirname(__file__), 'files', 'doorstop.css')
HTMLTEMPLATE = 'sidebar'
INDEX = 'index.html'

log = common.logger(__name__)


def publish(
    obj, path, ext=None, linkify=None, index=None, template=None, toc=True, **kwargs
):
    """Publish an object to a given format.

    The function can be called in two ways:

    1. document or item-like object + output file path
    2. tree-like object + output directory path

    :param obj: (1) Item, list of Items, Document or (2) Tree
    :param path: (1) output file path or (2) output directory path
    :param ext: file extension to override output extension
    :param linkify: turn links into hyperlinks (for Markdown or HTML)
    :param index: create an index.html (for HTML)

    :raises: :class:`doorstop.common.DoorstopError` for unknown file formats

    :return: output location if files created, else None

    """
    # Determine the output format
    ext = ext or os.path.splitext(path)[-1] or '.html'
    check(ext)
    if linkify is None:
        linkify = is_tree(obj) and ext in ['.html', '.md']
    if index is None:
        index = is_tree(obj) and ext == '.html'

    if is_tree(obj):
        assets_dir = os.path.join(path, Document.ASSETS)  # path is a directory name
    else:
        assets_dir = os.path.join(
            os.path.dirname(path), Document.ASSETS
        )  # path is a filename

    if os.path.isdir(assets_dir):
        log.info('Deleting contents of assets directory %s', assets_dir)
        common.delete_contents(assets_dir)
    else:
        os.makedirs(assets_dir)

    # If publish html and then markdown ensure that the html template are still available
    if not template:
        template = HTMLTEMPLATE
    template_assets = os.path.join(os.path.dirname(__file__), 'files', 'assets')
    if os.path.isdir(template_assets):
        log.info("Copying %s to %s", template_assets, assets_dir)
        common.copy_dir_contents(template_assets, assets_dir)

    # Publish documents
    count = 0
    for obj2, path2 in iter_documents(obj, path, ext):
        count += 1

        # Publish content to the specified path
        log.info("publishing to {}...".format(path2))
        lines = publish_lines(
            obj2, ext, linkify=linkify, template=template, toc=toc, **kwargs
        )
        common.write_lines(lines, path2)
        if obj2.copy_assets(assets_dir):
            log.info('Copied assets from %s to %s', obj.assets, assets_dir)

    # Create index
    if index and count:
        _index(path, tree=obj if is_tree(obj) else None)

    # Return the published path
    if count:
        msg = "published to {} file{}".format(count, 's' if count > 1 else '')
        log.info(msg)
        return path
    else:
        log.warning("nothing to publish")
        return None


def _index(directory, index=INDEX, extensions=('.html',), tree=None):
    """Create an HTML index of all files in a directory.

    :param directory: directory for index
    :param index: filename for index
    :param extensions: file extensions to include
    :param tree: optional tree to determine index structure

    """
    # Get paths for the index index
    filenames = []
    for filename in os.listdir(directory):
        if filename.endswith(extensions) and filename != INDEX:
            filenames.append(os.path.join(filename))

    # Create the index
    if filenames:
        path = os.path.join(directory, index)
        log.info("creating an {}...".format(index))
        lines = _lines_index(sorted(filenames), tree=tree)
        common.write_lines(lines, path)
    else:
        log.warning("no files for {}".format(index))


def _lines_index(filenames, charset='UTF-8', tree=None):
    """Yield lines of HTML for index.html.

    :param filesnames: list of filenames to add to the index
    :param charset: character encoding for output
    :param tree: optional tree to determine index structure

    """
    yield '<!DOCTYPE html>'
    yield '<head>'
    yield (
        '<meta http-equiv="content-type" content="text/html; '
        'charset={charset}">'.format(charset=charset)
    )
    yield '<style type="text/css">'
    yield from _lines_css()
    yield '</style>'
    yield '</head>'
    yield '<body>'
    # Tree structure
    text = tree.draw() if tree else None
    if text:
        yield ''
        yield '<h3>Tree Structure:</h3>'
        yield '<pre><code>' + text + '</pre></code>'
    # Additional files
    if filenames:
        if text:
            yield ''
            yield '<hr>'
        yield ''
        yield '<h3>Published Documents:</h3>'
        yield '<p>'
        yield '<ul>'
        for filename in filenames:
            name = os.path.splitext(filename)[0]
            yield '<li> <a href="{f}">{n}</a> </li>'.format(f=filename, n=name)
        yield '</ul>'
        yield '</p>'
    # Traceability table
    documents = tree.documents if tree else None
    if documents:
        if text or filenames:
            yield ''
            yield '<hr>'
        yield ''
        # table
        yield '<h3>Item Traceability:</h3>'
        yield '<p>'
        yield '<table>'
        # header
        for document in documents:
            yield '<col width="100">'
        yield '<tr>'
        for document in documents:
            link = '<a href="{p}.html">{p}</a>'.format(p=document.prefix)
            yield ('  <th height="25" align="center"> {link} </th>'.format(link=link))
        yield '</tr>'
        # data
        for index, row in enumerate(tree.get_traceability()):
            if index % 2:
                yield '<tr class="alt">'
            else:
                yield '<tr>'
            for item in row:
                if item is None:
                    link = ''
                else:
                    link = _format_html_item_link(item)
                yield '  <td height="25" align="center"> {} </td>'.format(link)
            yield '</tr>'
        yield '</table>'
        yield '</p>'
    yield ''
    yield '</body>'
    yield '</html>'


def _lines_css():
    """Yield lines of CSS to embedded in HTML."""
    yield ''
    for line in common.read_lines(CSS):
        yield line.rstrip()
    yield ''


def publish_lines(obj, ext='.txt', **kwargs):
    """Yield lines for a report in the specified format.

    :param obj: Item, list of Items, or Document to publish
    :param ext: file extension to specify the output format

    :raises: :class:`doorstop.common.DoorstopError` for unknown file formats

    """
    gen = check(ext)
    log.debug("yielding {} as lines of {}...".format(obj, ext))
    yield from gen(obj, **kwargs)


def _lines_text(obj, indent=8, width=79, **_):
    """Yield lines for a text report.

    :param obj: Item, list of Items, or Document to publish
    :param indent: number of spaces to indent text
    :param width: maximum line length

    :return: iterator of lines of text

    """
    for item in iter_items(obj):

        level = _format_level(item.level)

        if item.heading:

            # Level and Text
            if settings.PUBLISH_HEADING_LEVELS:
                yield "{lev:<{s}}{t}".format(lev=level, s=indent, t=item.text)
            else:
                yield "{t}".format(t=item.text)

        else:

            # Level and UID
            if item.header:
                yield "{lev:<{s}}{u} {header}".format(
                    lev=level, s=indent, u=item.uid, header=item.header
                )
            else:
                yield "{lev:<{s}}{u}".format(lev=level, s=indent, u=item.uid)

            # Text
            if item.text:
                yield ""  # break before text
                for line in item.text.splitlines():
                    yield from _chunks(line, width, indent)

                    if not line:
                        yield ""  # break between paragraphs

            # Reference
            if item.ref:
                yield ""  # break before reference
                ref = _format_text_ref(item)
                yield from _chunks(ref, width, indent)

            # Links
            if item.links:
                yield ""  # break before links
                if settings.PUBLISH_CHILD_LINKS:
                    label = "Parent links: "
                else:
                    label = "Links: "
                slinks = label + ', '.join(str(l) for l in item.links)
                yield from _chunks(slinks, width, indent)
            if settings.PUBLISH_CHILD_LINKS:
                links = item.find_child_links()
                if links:
                    yield ""  # break before links
                    slinks = "Child links: " + ', '.join(str(l) for l in links)
                    yield from _chunks(slinks, width, indent)

        yield ""  # break between items


def _chunks(text, width, indent):
    """Yield wrapped lines of text."""
    yield from textwrap.wrap(
        text, width, initial_indent=' ' * indent, subsequent_indent=' ' * indent
    )


def _lines_markdown(obj, **kwargs):
    """Yield lines for a Markdown report.

    :param obj: Item, list of Items, or Document to publish
    :param linkify: turn links into hyperlinks (for conversion to HTML)

    :return: iterator of lines of text

    """
    linkify = kwargs.get('linkify', False)
    for item in iter_items(obj):

        heading = '#' * item.depth
        level = _format_level(item.level)

        if item.heading:
            text_lines = item.text.splitlines()
            # Level and Text
            if settings.PUBLISH_HEADING_LEVELS:
                standard = "{h} {lev} {t}".format(
                    h=heading, lev=level, t=text_lines[0] if text_lines else ''
                )
            else:
                standard = "{h} {t}".format(
                    h=heading, t=text_lines[0] if text_lines else ''
                )
            attr_list = _format_md_attr_list(item, True)
            yield standard + attr_list
            yield from text_lines[1:]
        else:

            uid = item.uid
            if settings.ENABLE_HEADERS:
                if item.header:
                    uid = '{h} <small>{u}</small>'.format(h=item.header, u=item.uid)
                else:
                    uid = '{u}'.format(u=item.uid)

            # Level and UID
            if settings.PUBLISH_BODY_LEVELS:
                standard = "{h} {lev} {u}".format(h=heading, lev=level, u=uid)
            else:
                standard = "{h} {u}".format(h=heading, u=uid)

            attr_list = _format_md_attr_list(item, True)
            yield standard + attr_list

            # Text
            if item.text:
                yield ""  # break before text
                yield from item.text.splitlines()

            # Reference
            if item.ref:
                yield ""  # break before reference
                yield _format_md_ref(item)

            # Parent links
            if item.links:
                yield ""  # break before links
                items2 = item.parent_items
                if settings.PUBLISH_CHILD_LINKS:
                    label = "Parent links:"
                else:
                    label = "Links:"
                links = _format_md_links(items2, linkify)
                label_links = _format_md_label_links(label, links, linkify)
                yield label_links

            # Child links
            if settings.PUBLISH_CHILD_LINKS:
                items2 = item.find_child_items()
                if items2:
                    yield ""  # break before links
                    label = "Child links:"
                    links = _format_md_links(items2, linkify)
                    label_links = _format_md_label_links(label, links, linkify)
                    yield label_links

        yield ""  # break between items


def _format_level(level):
    """Convert a level to a string and keep zeros if not a top level."""
    text = str(level)
    if text.endswith('.0') and len(text) > 3:
        text = text[:-2]
    return text


def _format_md_attr_list(item, linkify):
    """Create a Markdown attribute list for a heading."""
    return " {{#{u} }}".format(u=item.uid) if linkify else ''


def _format_text_ref(item):
    """Format an external reference in text."""
    if settings.CHECK_REF:
        path, line = item.find_ref()
        path = path.replace('\\', '/')  # always use unix-style paths
        if line:
            return "Reference: {p} (line {line})".format(p=path, line=line)
        else:
            return "Reference: {p}".format(p=path)
    else:
        return "Reference: '{r}'".format(r=item.ref)


def _format_md_ref(item):
    """Format an external reference in Markdown."""
    if settings.CHECK_REF:
        path, line = item.find_ref()
        path = path.replace('\\', '/')  # always use unix-style paths
        if line:
            return "> `{p}` (line {line})".format(p=path, line=line)
        else:
            return "> `{p}`".format(p=path)
    else:
        return "> '{r}'".format(r=item.ref)


def _format_md_links(items, linkify):
    """Format a list of linked items in Markdown."""
    links = []
    for item in items:
        link = _format_md_item_link(item, linkify=linkify)
        links.append(link)
    return ', '.join(links)


def _format_md_item_link(item, linkify=True):
    """Format an item link in Markdown."""
    if linkify and is_item(item):
        if item.header:
            return "[{u} {h}]({p}.html#{u})".format(
                u=item.uid, h=item.header, p=item.document.prefix
            )
        return "[{u}]({p}.html#{u})".format(u=item.uid, p=item.document.prefix)
    else:
        return str(item.uid)  # if not `Item`, assume this is an `UnknownItem`


def _format_html_item_link(item, linkify=True):
    """Format an item link in HTML."""
    if linkify and is_item(item):
        if item.header:
            link = '<a href="{p}.html#{u}">{u} {h}</a>'.format(
                u=item.uid, h=item.header, p=item.document.prefix
            )
        else:
            link = '<a href="{p}.html#{u}">{u}</a>'.format(
                u=item.uid, p=item.document.prefix
            )
        return link
    else:
        return str(item.uid)  # if not `Item`, assume this is an `UnknownItem`


def _format_md_label_links(label, links, linkify):
    """Join a string of label and links with formatting."""
    if linkify:
        return "*{lb}* {ls}".format(lb=label, ls=links)
    else:
        return "*{lb} {ls}*".format(lb=label, ls=links)


def _table_of_contents_md(obj, linkify=None):
    toc = '### Table of Contents\n\n'

    for item in iter_items(obj):
        if item.depth == 1:
            prefix = ' * '
        else:
            prefix = '    ' * (item.depth - 1)
            prefix += '* '

        if item.heading:
            lines = item.text.splitlines()
            heading = lines[0] if lines else ''
        elif item.header:
            heading = "{h}".format(h=item.header)
        else:
            heading = item.uid

        if settings.PUBLISH_HEADING_LEVELS:
            level = _format_level(item.level)
            lbl = '{lev} {h}'.format(lev=level, h=heading)
        else:
            lbl = heading

        if linkify:
            line = '{p}[{lbl}](#{uid})\n'.format(p=prefix, lbl=lbl, uid=item.uid)
        else:
            line = '{p}{lbl}\n'.format(p=prefix, lbl=lbl)
        toc += line
    return toc


def _lines_html(
    obj, linkify=False, extensions=EXTENSIONS, template=HTMLTEMPLATE, toc=True
):
    """Yield lines for an HTML report.

    :param obj: Item, list of Items, or Document to publish
    :param linkify: turn links into hyperlinks

    :return: iterator of lines of text

    """
    # Determine if a full HTML document should be generated
    try:
        iter(obj)
    except TypeError:
        document = False
    else:
        document = True
    # Generate HTML

    text = '\n'.join(_lines_markdown(obj, linkify=linkify))
    body = markdown.markdown(text, extensions=extensions)

    if toc:
        toc_md = _table_of_contents_md(obj, True)
        toc_html = markdown.markdown(toc_md, extensions=extensions)
    else:
        toc_html = ''

    if document:
        try:
            bottle.TEMPLATE_PATH.insert(
                0, os.path.join(os.path.dirname(__file__), '..', 'views')
            )
            if 'baseurl' not in bottle.SimpleTemplate.defaults:
                bottle.SimpleTemplate.defaults['baseurl'] = ''
            html = bottle_template(
                template, body=body, toc=toc_html, parent=obj.parent, document=obj
            )
        except Exception:
            log.error("Problem parsing the template %s", template)
            raise
        yield '\n'.join(html.split(os.linesep))
    else:
        yield body


# Mapping from file extension to lines generator
FORMAT_LINES = {'.txt': _lines_text, '.md': _lines_markdown, '.html': _lines_html}


def check(ext):
    """Confirm an extension is supported for publish.

    :raises: :class:`doorstop.common.DoorstopError` for unknown formats

    :return: lines generator if available

    """
    exts = ', '.join(ext for ext in FORMAT_LINES)
    msg = "unknown publish format: {} (options: {})".format(ext or None, exts)
    exc = DoorstopError(msg)

    try:
        gen = FORMAT_LINES[ext]
    except KeyError:
        raise exc from None
    else:
        log.debug("found lines generator for: {}".format(ext))
        return gen


1		# SPDX-License-Identifier: LGPL-3.0-only
2
3	1	"""Functions to publish documents and items."""
4	1
5	1	import os
6		import tempfile
7	1	import textwrap
8
9	1	import bottle
10	1	import markdown
11	1	from bottle import template as bottle_template
		0 ignored issues – show introduced 2019-07-12 13:21 UTC by Report Bug Copy Issue Report third party import "from bottle import template as bottle_template" should be placed before "import markdown" Loading history...
12	1	from plantuml_markdown import PlantUMLMarkdownExtension
13	1
14		from doorstop import common, settings
15	1	from doorstop.common import DoorstopError
16		from doorstop.core import Document
17		from doorstop.core.types import is_item, is_tree, iter_documents, iter_items
18
19	1	EXTENSIONS = (
20	1	'markdown.extensions.extra',
21	1	'markdown.extensions.sane_lists',
22		'mdx_outline',
23	1	'mdx_math',
24		PlantUMLMarkdownExtension(
25		server='http://www.plantuml.com/plantuml',
26	1	cachedir=tempfile.gettempdir(),
27		format='svg',
28		classes='class1,class2',
29		title='UML',
30		alt='UML Diagram',
31		),
32		)
33		CSS = os.path.join(os.path.dirname(__file__), 'files', 'doorstop.css')
34		HTMLTEMPLATE = 'sidebar'
35		INDEX = 'index.html'
36
37		log = common.logger(__name__)
38
39
40		def publish(
41		obj, path, ext=None, linkify=None, index=None, template=None, toc=True, **kwargs
42		):
43		"""Publish an object to a given format.
44
45		The function can be called in two ways:
46
47	1	1. document or item-like object + output file path
48	1	2. tree-like object + output directory path
49	1
50	1	:param obj: (1) Item, list of Items, Document or (2) Tree
51	1	:param path: (1) output file path or (2) output directory path
52	1	:param ext: file extension to override output extension
53		:param linkify: turn links into hyperlinks (for Markdown or HTML)
54	1	:param index: create an index.html (for HTML)
55	1
56		:raises: :class:`doorstop.common.DoorstopError` for unknown file formats
57	1
58		:return: output location if files created, else None
59	1
60	1	"""
61	1	# Determine the output format
62		ext = ext or os.path.splitext(path)[-1] or '.html'
63	1	check(ext)
64		if linkify is None:
65		linkify = is_tree(obj) and ext in ['.html', '.md']
66	1	if index is None:
67	1	index = is_tree(obj) and ext == '.html'
68	1
69	1	if is_tree(obj):
70	1	assets_dir = os.path.join(path, Document.ASSETS) # path is a directory name
71	1	else:
72		assets_dir = os.path.join(
73		os.path.dirname(path), Document.ASSETS
74	1	) # path is a filename
75	1
76	1	if os.path.isdir(assets_dir):
77		log.info('Deleting contents of assets directory %s', assets_dir)
78		common.delete_contents(assets_dir)
79	1	else:
80	1	os.makedirs(assets_dir)
81
82	1	# If publish html and then markdown ensure that the html template are still available
83	1	if not template:
84	1	template = HTMLTEMPLATE
85		template_assets = os.path.join(os.path.dirname(__file__), 'files', 'assets')
86		if os.path.isdir(template_assets):
87	1	log.info("Copying %s to %s", template_assets, assets_dir)
88	1	common.copy_dir_contents(template_assets, assets_dir)
89
90		# Publish documents
91	1	count = 0
92	1	for obj2, path2 in iter_documents(obj, path, ext):
93	1	count += 1
94	1
95		# Publish content to the specified path
96		log.info("publishing to {}...".format(path2))
97		lines = publish_lines(
98		obj2, ext, linkify=linkify, template=template, toc=toc, **kwargs
99		)
100	1	common.write_lines(lines, path2)
101		if obj2.copy_assets(assets_dir):
102		log.info('Copied assets from %s to %s', obj.assets, assets_dir)
103
104		# Create index
105		if index and count:
106		_index(path, tree=obj if is_tree(obj) else None)
107
108		# Return the published path
109		if count:
110	1	msg = "published to {} file{}".format(count, 's' if count > 1 else '')
111	1	log.info(msg)
112	1	return path
113	1	else:
114		log.warning("nothing to publish")
115		return None
116	1
117	1
118	1	def _index(directory, index=INDEX, extensions=('.html',), tree=None):
119	1	"""Create an HTML index of all files in a directory.
120	1
121		:param directory: directory for index
122	1	:param index: filename for index
123		:param extensions: file extensions to include
124		:param tree: optional tree to determine index structure
125	1
126		"""
127		# Get paths for the index index
128		filenames = []
129		for filename in os.listdir(directory):
130		if filename.endswith(extensions) and filename != INDEX:
131		filenames.append(os.path.join(filename))
132
133	1	# Create the index
134	1	if filenames:
135	1	path = os.path.join(directory, index)
136		log.info("creating an {}...".format(index))
137	1	lines = _lines_index(sorted(filenames), tree=tree)
138	1	common.write_lines(lines, path)
139	1	else:
140	1	log.warning("no files for {}".format(index))
141	1
142
143	1	def _lines_index(filenames, charset='UTF-8', tree=None):
144	1	"""Yield lines of HTML for index.html.
145	1
146	1	:param filesnames: list of filenames to add to the index
147	1	:param charset: character encoding for output
148		:param tree: optional tree to determine index structure
149	1
150	1	"""
151	1	yield '<!DOCTYPE html>'
152	1	yield '<head>'
153	1	yield (
154	1	'<meta http-equiv="content-type" content="text/html; '
155	1	'charset={charset}">'.format(charset=charset)
156	1	)
157	1	yield '<style type="text/css">'
158	1	yield from _lines_css()
159	1	yield '</style>'
160	1	yield '</head>'
161	1	yield '<body>'
162		# Tree structure
163	1	text = tree.draw() if tree else None
164	1	if text:
165	1	yield ''
166	1	yield '<h3>Tree Structure:</h3>'
167	1	yield '<pre><code>' + text + '</pre></code>'
168	1	# Additional files
169		if filenames:
170	1	if text:
171	1	yield ''
172	1	yield '<hr>'
173		yield ''
174	1	yield '<h3>Published Documents:</h3>'
175	1	yield '<p>'
176	1	yield '<ul>'
177	1	for filename in filenames:
178	1	name = os.path.splitext(filename)[0]
179	1	yield '<li> <a href="{f}">{n}</a> </li>'.format(f=filename, n=name)
180	1	yield '</ul>'
181		yield '</p>'
182	1	# Traceability table
183	1	documents = tree.documents if tree else None
184	1	if documents:
185		if text or filenames:
186	1	yield ''
187	1	yield '<hr>'
188	1	yield ''
189	1	# table
190		yield '<h3>Item Traceability:</h3>'
191	1	yield '<p>'
192	1	yield '<table>'
193	1	# header
194	1	for document in documents:
195	1	yield '<col width="100">'
196	1	yield '<tr>'
197	1	for document in documents:
198	1	link = '<a href="{p}.html">{p}</a>'.format(p=document.prefix)
199		yield (' <th height="25" align="center"> {link} </th>'.format(link=link))
200		yield '</tr>'
201	1	# data
202		for index, row in enumerate(tree.get_traceability()):
203	1	if index % 2:
204	1	yield '<tr class="alt">'
205	1	else:
206	1	yield '<tr>'
207		for item in row:
208		if item is None:
209	1	link = ''
210		else:
211		link = _format_html_item_link(item)
212		yield ' <td height="25" align="center"> {} </td>'.format(link)
213		yield '</tr>'
214		yield '</table>'
215		yield '</p>'
216		yield ''
217		yield '</body>'
218	1	yield '</html>'
219	1
220	1
221		def _lines_css():
222		"""Yield lines of CSS to embedded in HTML."""
223	1	yield ''
224		for line in common.read_lines(CSS):
225		yield line.rstrip()
226		yield ''
227
228
229		def publish_lines(obj, ext='.txt', **kwargs):
230		"""Yield lines for a report in the specified format.
231
232		:param obj: Item, list of Items, or Document to publish
233	1	:param ext: file extension to specify the output format
234
235	1	:raises: :class:`doorstop.common.DoorstopError` for unknown file formats
236
237	1	"""
238		gen = check(ext)
239		log.debug("yielding {} as lines of {}...".format(obj, ext))
240	1	yield from gen(obj, **kwargs)
241	1
242
243	1	def _lines_text(obj, indent=8, width=79, **_):
244		"""Yield lines for a text report.
245
246		:param obj: Item, list of Items, or Document to publish
247		:param indent: number of spaces to indent text
248	1	:param width: maximum line length
249
250		:return: iterator of lines of text
251	1
252	1	"""
253	1	for item in iter_items(obj):
254	1
255		level = _format_level(item.level)
256
257		if item.heading:
258
259		# Level and Text
260	1	if settings.PUBLISH_HEADING_LEVELS:
261	1	yield "{lev:<{s}}{t}".format(lev=level, s=indent, t=item.text)
262	1	else:
263	1	yield "{t}".format(t=item.text)
264
265		else:
266	1
267	1	# Level and UID
268	1	if item.header:
269	1	yield "{lev:<{s}}{u} {header}".format(
270		lev=level, s=indent, u=item.uid, header=item.header
271	1	)
272	1	else:
273	1	yield "{lev:<{s}}{u}".format(lev=level, s=indent, u=item.uid)
274	1
275	1	# Text
276	1	if item.text:
277	1	yield "" # break before text
278	1	for line in item.text.splitlines():
279	1	yield from _chunks(line, width, indent)
280
281	1	if not line:
282		yield "" # break between paragraphs
283
284	1	# Reference
285		if item.ref:
286	1	yield "" # break before reference
287		ref = _format_text_ref(item)
288		yield from _chunks(ref, width, indent)
289
290		# Links
291	1	if item.links:
292		yield "" # break before links
293		if settings.PUBLISH_CHILD_LINKS:
294		label = "Parent links: "
295		else:
296		label = "Links: "
297		slinks = label + ', '.join(str(l) for l in item.links)
298		yield from _chunks(slinks, width, indent)
299		if settings.PUBLISH_CHILD_LINKS:
300	1	links = item.find_child_links()
301		if links:
302	1	yield "" # break before links
303	1	slinks = "Child links: " + ', '.join(str(l) for l in links)
304		yield from _chunks(slinks, width, indent)
305	1
306	1	yield "" # break between items
307
308	1
309	1	def _chunks(text, width, indent):
310		"""Yield wrapped lines of text."""
311	1	yield from textwrap.wrap(
312	1	text, width, initial_indent=' ' * indent, subsequent_indent=' ' * indent
313	1	)
314	1
315
316		def _lines_markdown(obj, **kwargs):
317		"""Yield lines for a Markdown report.
318	1
319	1	:param obj: Item, list of Items, or Document to publish
320		:param linkify: turn links into hyperlinks (for conversion to HTML)
321	1
322	1	:return: iterator of lines of text
323	1
324		"""
325		linkify = kwargs.get('linkify', False)
326	1	for item in iter_items(obj):
327	1
328	1	heading = '#' * item.depth
329		level = _format_level(item.level)
330
331	1	if item.heading:
332	1	text_lines = item.text.splitlines()
333	1	# Level and Text
334		if settings.PUBLISH_HEADING_LEVELS:
335		standard = "{h} {lev} {t}".format(
336	1	h=heading, lev=level, t=text_lines[0] if text_lines else ''
337	1	)
338	1	else:
339	1	standard = "{h} {t}".format(
340	1	h=heading, t=text_lines[0] if text_lines else ''
341		)
342	1	attr_list = _format_md_attr_list(item, True)
343	1	yield standard + attr_list
344	1	yield from text_lines[1:]
345	1	else:
346
347		uid = item.uid
348	1	if settings.ENABLE_HEADERS:
349	1	if item.header:
350	1	uid = '{h} <small>{u}</small>'.format(h=item.header, u=item.uid)
351	1	else:
352	1	uid = '{u}'.format(u=item.uid)
353	1
354	1	# Level and UID
355	1	if settings.PUBLISH_BODY_LEVELS:
356		standard = "{h} {lev} {u}".format(h=heading, lev=level, u=uid)
357	1	else:
358		standard = "{h} {u}".format(h=heading, u=uid)
359
360	1	attr_list = _format_md_attr_list(item, True)
361		yield standard + attr_list
362	1
363	1	# Text
364	1	if item.text:
365	1	yield "" # break before text
366		yield from item.text.splitlines()
367
368	1	# Reference
369		if item.ref:
370	1	yield "" # break before reference
371		yield _format_md_ref(item)
372
373	1	# Parent links
374		if item.links:
375	1	yield "" # break before links
376	1	items2 = item.parent_items
377	1	if settings.PUBLISH_CHILD_LINKS:
378	1	label = "Parent links:"
379	1	else:
380		label = "Links:"
381	1	links = _format_md_links(items2, linkify)
382		label_links = _format_md_label_links(label, links, linkify)
383	1	yield label_links
384
385		# Child links
386	1	if settings.PUBLISH_CHILD_LINKS:
387		items2 = item.find_child_items()
388	1	if items2:
389	1	yield "" # break before links
390	1	label = "Child links:"
391	1	links = _format_md_links(items2, linkify)
392	1	label_links = _format_md_label_links(label, links, linkify)
393		yield label_links
394	1
395		yield "" # break between items
396	1
397
398		def _format_level(level):
399	1	"""Convert a level to a string and keep zeros if not a top level."""
400		text = str(level)
401	1	if text.endswith('.0') and len(text) > 3:
402	1	text = text[:-2]
403	1	return text
404	1
405	1
406		def _format_md_attr_list(item, linkify):
407		"""Create a Markdown attribute list for a heading."""
408	1	return " {{#{u} }}".format(u=item.uid) if linkify else ''
409
410	1
411	1	def _format_text_ref(item):
412		"""Format an external reference in text."""
413	1	if settings.CHECK_REF:
414		path, line = item.find_ref()
415		path = path.replace('\\', '/') # always use unix-style paths
416	1	if line:
417		return "Reference: {p} (line {line})".format(p=path, line=line)
418	1	else:
419	1	return "Reference: {p}".format(p=path)
420		else:
421	1	return "Reference: '{r}'".format(r=item.ref)
422
423	1
424		def _format_md_ref(item):
425		"""Format an external reference in Markdown."""
426	1	if settings.CHECK_REF:
427		path, line = item.find_ref()
428	1	path = path.replace('\\', '/') # always use unix-style paths
429	1	if line:
430		return "> `{p}` (line {line})".format(p=path, line=line)
431	1	else:
432		return "> `{p}`".format(p=path)
433		else:
434	1	return "> '{r}'".format(r=item.ref)
435	1
436
437	1	def _format_md_links(items, linkify):
438	1	"""Format a list of linked items in Markdown."""
439	1	links = []
440		for item in items:
441	1	link = _format_md_item_link(item, linkify=linkify)
442	1	links.append(link)
443		return ', '.join(links)
444	1
445	1
446	1	def _format_md_item_link(item, linkify=True):
447		"""Format an item link in Markdown."""
448	1	if linkify and is_item(item):
449		if item.header:
450	1	return "[{u} {h}]({p}.html#{u})".format(
451	1	u=item.uid, h=item.header, p=item.document.prefix
452	1	)
453		return "[{u}]({p}.html#{u})".format(u=item.uid, p=item.document.prefix)
454	1	else:
455		return str(item.uid) # if not `Item`, assume this is an `UnknownItem`
456	1
457	1
458		def _format_html_item_link(item, linkify=True):
459		"""Format an item link in HTML."""
460		if linkify and is_item(item):
461	1	if item.header:
462		link = '<a href="{p}.html#{u}">{u} {h}</a>'.format(
463	1	u=item.uid, h=item.header, p=item.document.prefix
464	1	)
465		else:
466		link = '<a href="{p}.html#{u}">{u}</a>'.format(
467	1	u=item.uid, p=item.document.prefix
468		)
469		return link
470		else:
471		return str(item.uid) # if not `Item`, assume this is an `UnknownItem`
472
473
474		def _format_md_label_links(label, links, linkify):
475		"""Join a string of label and links with formatting."""
476		if linkify:
477		return "{lb} {ls}".format(lb=label, ls=links)
478	1	else:
479	1	return "{lb} {ls}".format(lb=label, ls=links)
480	1
481	1
482		def _table_of_contents_md(obj, linkify=None):
483	1	toc = '### Table of Contents\n\n'
484
485		for item in iter_items(obj):
486	1	if item.depth == 1:
487	1	prefix = ' * '
488		else:
489	1	prefix = ' ' * (item.depth - 1)
490	1	prefix += '* '
491	1
492		if item.heading:
493		lines = item.text.splitlines()
494		heading = lines[0] if lines else ''
495	1	elif item.header:
496	1	heading = "{h}".format(h=item.header)
497	1	else:
498	1	heading = item.uid
499	1
500	1	if settings.PUBLISH_HEADING_LEVELS:
501		level = _format_level(item.level)
502		lbl = '{lev} {h}'.format(lev=level, h=heading)
503		else:
504	1	lbl = heading
505
506	1	if linkify:
507		line = '{p}[{lbl}](#{uid})\n'.format(p=prefix, lbl=lbl, uid=item.uid)
508		else:
509		line = '{p}{lbl}\n'.format(p=prefix, lbl=lbl)
510	1	toc += line
511		return toc
512
513
514		def _lines_html(
515	1	obj, linkify=False, extensions=EXTENSIONS, template=HTMLTEMPLATE, toc=True
516		):
517		"""Yield lines for an HTML report.
518
519		:param obj: Item, list of Items, or Document to publish
520		:param linkify: turn links into hyperlinks
521
522		:return: iterator of lines of text
523	1
524	1	"""
525	1	# Determine if a full HTML document should be generated
526		try:
527	1	iter(obj)
528	1	except TypeError:
529	1	document = False
530	1	else:
531		document = True
532	1	# Generate HTML
533	1
534		text = '\n'.join(_lines_markdown(obj, linkify=linkify))
535		body = markdown.markdown(text, extensions=extensions)
536
537		if toc:
538		toc_md = _table_of_contents_md(obj, True)
539		toc_html = markdown.markdown(toc_md, extensions=extensions)
540		else:
541		toc_html = ''
542
543		if document:
544		try:
545		bottle.TEMPLATE_PATH.insert(
546		0, os.path.join(os.path.dirname(__file__), '..', 'views')
547		)
548		if 'baseurl' not in bottle.SimpleTemplate.defaults:
549		bottle.SimpleTemplate.defaults['baseurl'] = ''
550		html = bottle_template(
551		template, body=body, toc=toc_html, parent=obj.parent, document=obj
552		)
553		except Exception:
554		log.error("Problem parsing the template %s", template)
555		raise
556		yield '\n'.join(html.split(os.linesep))
557		else:
558		yield body
559
560
561		# Mapping from file extension to lines generator
562		FORMAT_LINES = {'.txt': _lines_text, '.md': _lines_markdown, '.html': _lines_html}
563
564
565		def check(ext):
566		"""Confirm an extension is supported for publish.
567
568		:raises: :class:`doorstop.common.DoorstopError` for unknown formats
569
570		:return: lines generator if available
571
572		"""
573		exts = ', '.join(ext for ext in FORMAT_LINES)
574		msg = "unknown publish format: {} (options: {})".format(ext or None, exts)
575		exc = DoorstopError(msg)
576
577		try:
578		gen = FORMAT_LINES[ext]
579		except KeyError:
580		raise exc from None
581		else:
582		log.debug("found lines generator for: {}".format(ext))
583		return gen
584

jacebrowning / doorstop

doorstop.core.publisher.publish() F last analyzed 2019-08-12 00:16 UTC

Complexity

Size

Duplication

Code Coverage

Importance

How to fix Long Method Complexity Many Parameters

Long Method

Complexity

Many Parameters

Duplication Side-by-Side

Filter issues like

doorstop.core.publisher.publish() F
last analyzed 2019-08-12 00:16 UTC