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

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

↳ Parent: doorstop.core.publisher

Complexity

Conditions

Size

Total Lines	6
Code Lines	5

Duplication

Lines	0
Ratio	0 %

Code Coverage

Tests	1
CRAP Score	2

Importance

Changes

Metric	Value
eloc	5
dl	0
loc	6
ccs	1
cts	1
cp	1
rs	10
c	0
b	0
f	0
cc	2
nop	0
crap	2

# 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._lines_css() A last analyzed 2019-08-12 00:16 UTC

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like

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