doorstop.core.publishers.markdown.MarkdownPublisher.lines_index() - Code Metrics - doorstop-dev/doorstop - Measure and Improve Code Quality continuously with Scrutinizer

MarkdownPublisher.lines_index() A
last analyzed 2025-06-26 14:29 UTC

↳ Parent: doorstop.core.publishers.markdown

Complexity

Conditions

Size

Total Lines	16
Code Lines	9

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
eloc	9
dl	0
loc	16
rs	9.95
c	0
b	0
f	0
cc	4
nop	3

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

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

import os
from re import sub

from doorstop import common, settings
from doorstop.core.publishers.base import (
    BasePublisher,
    extract_prefix,
    format_level,
    get_document_attributes,
)
from doorstop.core.types import is_item, iter_items

log = common.logger(__name__)
INDEX = "index.md"


class MarkdownPublisher(BasePublisher):
    """Markdown publisher."""

    def create_index(self, directory, index=INDEX, extensions=(".md",), tree=None):
        """Create an markdown 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 = self.lines_index(sorted(filenames), tree=tree)
            common.write_text("# Requirements index\n" + "\n".join(lines), path)
        else:
            log.warning("no files for {}".format(index))

    def _index_tree(self, tree, depth):
        """Recursively generate markdown index.

        :param tree: optional tree to determine index structure
        :param depth: depth recursed into tree
        """

        depth = depth + 1

        title = get_document_attributes(tree.document)["title"]
        prefix = extract_prefix(tree.document)
        filename = f"{prefix}.md"

        # Tree structure
        yield " " * (depth * 2 - 1) + f"* [{prefix}]({filename}) - {title}"
        # yield self.table_of_contents(linkify=True, obj=tree.document, depth=depth, heading=False)
        for child in tree.children:
            yield from self._index_tree(tree=child, depth=depth)

    def lines_index(self, filenames, tree=None):
        """Yield lines of Markdown for index.md.

        :param filenames: list of filenames to add to the index
        :param tree: optional tree to determine index structure
        """
        if tree:
            yield from self._index_tree(tree, depth=0)

        # Additional files
        if filenames:
            yield ""
            yield "### Published Documents:"
            for filename in filenames:
                name = os.path.splitext(filename)[0]
                yield " * [{n}]({f})".format(f=filename, n=name)

    def create_matrix(self, directory):
        """No traceability matrix for Markdown."""

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

    def format_ref(self, 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_references(self, item):

        """Format an external reference in Markdown."""
        if settings.CHECK_REF:
            references = item.find_references()
            text_refs = []
            for ref_item in references:
                path, line = ref_item
                path = path.replace("\\", "/")  # always use unix-style paths

                if line:
                    text_refs.append("> `{p}` (line {line})".format(p=path, line=line))
                else:
                    text_refs.append("> `{p}`".format(p=path))

            return "\n".join(ref for ref in text_refs)
        else:
            references = item.references
            text_refs = []
            for ref_item in references:
                path = ref_item["path"]
                path = path.replace("\\", "/")  # always use unix-style paths
                text_refs.append("> '{r}'".format(r=path))
            return "\n".join(ref for ref in text_refs)

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

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

    def format_label_links(self, 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(self, linkify=None, obj=None):
        """Generate a table of contents for a Markdown document."""

        toc = "### Table of Contents\n\n"
        toc_doc = obj

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

            # Check if item has the attribute heading.
            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:
                link = clean_link(self._generate_heading_from_item(item))
                line = "{p}[{lbl}](#{l})\n".format(p=prefix, lbl=lbl, l=link)
            else:
                line = "{p}{lbl}\n".format(p=prefix, lbl=lbl)
            toc += line
        return toc

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

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

        :return: iterator of lines of text

        """
        linkify = kwargs.get("linkify", False)
        toc = kwargs.get("toc", False)
        if toc:
            yield self.table_of_contents(linkify=linkify, obj=obj)

        yield from self._lines_markdown(obj, **kwargs)

    def _generate_heading_from_item(self, item, to_html=False):
        """Generate a heading from an item in a consistent way for Markdown.

        This ensures that references between documents are consistent.
        """
        result = ""
        heading = "#" * item.depth
        level = format_level(item.level)
        if item.heading:
            text_lines = item.text.splitlines()
            if item.header:
                text_lines.insert(0, item.header)
            # 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 = self.format_attr_list(item, True)
            result = standard + attr_list
        else:
            uid = item.uid
            if settings.ENABLE_HEADERS:
                if item.header:
                    if to_html:
                        uid = "{h} <small>{u}</small>".format(h=item.header, u=item.uid)
                    else:
                        uid = "{h} _{u}_".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 = self.format_attr_list(item, True)
            result = standard + attr_list
        return result

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

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

        :return: iterator of lines of text

        """
        linkify = kwargs.get("linkify", False)
        to_html = kwargs.get("to_html", False)
        for item in iter_items(obj):
            # Create iten heading.
            complete_heading = self._generate_heading_from_item(item, to_html=to_html)
            yield complete_heading

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

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

            # Reference
            if item.references:
                yield ""  # break before reference
                yield self.format_references(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 = self.format_links(items2, linkify)
                label_links = self.format_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 = self.format_links(items2, linkify)
                    label_links = self.format_label_links(label, links, linkify)
                    yield label_links

            # Add custom publish attributes
            if item.document and item.document.publish:
                header_printed = False
                for attr in item.document.publish:
                    if not item.attribute(attr):
                        continue
                    if not header_printed:
                        header_printed = True
                        yield ""
                        yield "| Attribute | Value |"
                        yield "| --------- | ----- |"
                    yield "| {} | {} |".format(attr, item.attribute(attr))
                yield ""

            yield ""  # break between items


def clean_link(uid):
    """Clean a UID for use in a link.

    1. Strip leading # and spaces.
    2. Only smallcaps are allowed.
    3. Spaces are replaced with hyphens.
    5. All other special characters are removed.
    """
    uid = sub(r"^#*\s*", "", uid)
    uid = uid.lower()
    uid = uid.replace(" ", "-")
    uid = sub("[^a-z0-9-]", "", uid)
    return uid


1		# SPDX-License-Identifier: LGPL-3.0-only
2
3		"""Functions to publish documents and items."""
4
5		import os
6		from re import sub
7
8		from doorstop import common, settings
9		from doorstop.core.publishers.base import (
10		BasePublisher,
11		extract_prefix,
12		format_level,
13		get_document_attributes,
14		)
15		from doorstop.core.types import is_item, iter_items
16
17		log = common.logger(__name__)
18		INDEX = "index.md"
19
20
21		class MarkdownPublisher(BasePublisher):
22		"""Markdown publisher."""
23
24		def create_index(self, directory, index=INDEX, extensions=(".md",), tree=None):
25		"""Create an markdown index of all files in a directory.
26
27		:param directory: directory for index
28		:param index: filename for index
29		:param extensions: file extensions to include
30		:param tree: optional tree to determine index structure
31
32		"""
33		# Get paths for the index index
34		filenames = []
35		for filename in os.listdir(directory):
36		if filename.endswith(extensions) and filename != INDEX:
37		filenames.append(os.path.join(filename))
38
39		# Create the index
40		if filenames:
41		path = os.path.join(directory, index)
42		log.info("creating an {}...".format(index))
43		lines = self.lines_index(sorted(filenames), tree=tree)
44		common.write_text("# Requirements index\n" + "\n".join(lines), path)
45		else:
46		log.warning("no files for {}".format(index))
47
48		def _index_tree(self, tree, depth):
49		"""Recursively generate markdown index.
50
51		:param tree: optional tree to determine index structure
52		:param depth: depth recursed into tree
53		"""
54
55		depth = depth + 1
56
57		title = get_document_attributes(tree.document)["title"]
58		prefix = extract_prefix(tree.document)
59		filename = f"{prefix}.md"
60
61		# Tree structure
62		yield " " * (depth * 2 - 1) + f"* [{prefix}]({filename}) - {title}"
63		# yield self.table_of_contents(linkify=True, obj=tree.document, depth=depth, heading=False)
64		for child in tree.children:
65		yield from self._index_tree(tree=child, depth=depth)
66
67		def lines_index(self, filenames, tree=None):
68		"""Yield lines of Markdown for index.md.
69
70		:param filenames: list of filenames to add to the index
71		:param tree: optional tree to determine index structure
72		"""
73		if tree:
74		yield from self._index_tree(tree, depth=0)
75
76		# Additional files
77		if filenames:
78		yield ""
79		yield "### Published Documents:"
80		for filename in filenames:
81		name = os.path.splitext(filename)[0]
82		yield " * [{n}]({f})".format(f=filename, n=name)
83
84		def create_matrix(self, directory):
85		"""No traceability matrix for Markdown."""
86
87		def format_attr_list(self, item, linkify):
88		"""Create a Markdown attribute list for a heading."""
89		return " {{#{u}}}".format(u=item.uid) if linkify else ""
90
91	View Code Duplication	def format_ref(self, item):
		0 ignored issues – show Duplication introduced 2024-01-10 14:52 UTC by Report Bug Copy Issue Report This code seems to be duplicated in your project. Loading history...
92		"""Format an external reference in Markdown."""
93		if settings.CHECK_REF:
94		path, line = item.find_ref()
95		path = path.replace("\\", "/") # always use unix-style paths
96		if line:
97		return "> `{p}` (line {line})".format(p=path, line=line)
98		else:
99		return "> `{p}`".format(p=path)
100		else:
101		return "> '{r}'".format(r=item.ref)
102
103	View Code Duplication	def format_references(self, item):
		0 ignored issues – show Duplication introduced 2024-01-10 14:52 UTC by Report Bug Copy Issue Report This code seems to be duplicated in your project. Loading history...
104		"""Format an external reference in Markdown."""
105		if settings.CHECK_REF:
106		references = item.find_references()
107		text_refs = []
108		for ref_item in references:
109		path, line = ref_item
110		path = path.replace("\\", "/") # always use unix-style paths
111
112		if line:
113		text_refs.append("> `{p}` (line {line})".format(p=path, line=line))
114		else:
115		text_refs.append("> `{p}`".format(p=path))
116
117		return "\n".join(ref for ref in text_refs)
118		else:
119		references = item.references
120		text_refs = []
121		for ref_item in references:
122		path = ref_item["path"]
123		path = path.replace("\\", "/") # always use unix-style paths
124		text_refs.append("> '{r}'".format(r=path))
125		return "\n".join(ref for ref in text_refs)
126
127		def format_links(self, items, linkify):
128		"""Format a list of linked items in Markdown."""
129		links = []
130		for item in items:
131		link = self.format_item_link(item, linkify=linkify)
132		links.append(link)
133		return ", ".join(links)
134
135		def format_item_link(self, item, linkify=True):
136		"""Format an item link in Markdown."""
137		if linkify and is_item(item):
138		link = clean_link("{u}".format(u=self._generate_heading_from_item(item)))
139		if item.header:
140		return "[{u} {h}]({p}.md#{l})".format(
141		u=item.uid, l=link, h=item.header, p=item.document.prefix
142		)
143		return "[{u}]({p}.md#{l})".format(
144		u=item.uid, l=link, p=item.document.prefix
145		)
146		else:
147		return str(item.uid) # if not `Item`, assume this is an `UnknownItem`
148
149		def format_label_links(self, label, links, linkify):
150		"""Join a string of label and links with formatting."""
151		if linkify:
152		return "{lb} {ls}".format(lb=label, ls=links)
153		else:
154		return "{lb} {ls}".format(lb=label, ls=links)
155
156		def table_of_contents(self, linkify=None, obj=None):
157		"""Generate a table of contents for a Markdown document."""
158
159		toc = "### Table of Contents\n\n"
160		toc_doc = obj
161
162		for item in iter_items(toc_doc):
163		if item.depth == 1:
164		prefix = " * "
165		else:
166		prefix = " " * (item.depth - 1)
167		prefix += "* "
168
169		# Check if item has the attribute heading.
170		if item.heading:
171		lines = item.text.splitlines()
172		heading = lines[0] if lines else ""
173		elif item.header:
174		heading = "{h}".format(h=item.header)
175		else:
176		heading = item.uid
177
178		if settings.PUBLISH_HEADING_LEVELS:
179		level = format_level(item.level)
180		lbl = "{lev} {h}".format(lev=level, h=heading)
181		else:
182		lbl = heading
183
184		if linkify:
185		link = clean_link(self._generate_heading_from_item(item))
186		line = "{p}[{lbl}](#{l})\n".format(p=prefix, lbl=lbl, l=link)
187		else:
188		line = "{p}{lbl}\n".format(p=prefix, lbl=lbl)
189		toc += line
190		return toc
191
192		def lines(self, obj, **kwargs):
193		"""Yield lines for a Markdown report.
194
195		:param obj: Item, list of Items, or Document to publish
196		:param linkify: turn links into hyperlinks
197
198		:return: iterator of lines of text
199
200		"""
201		linkify = kwargs.get("linkify", False)
202		toc = kwargs.get("toc", False)
203		if toc:
204		yield self.table_of_contents(linkify=linkify, obj=obj)
205
206		yield from self._lines_markdown(obj, **kwargs)
207
208		def _generate_heading_from_item(self, item, to_html=False):
209		"""Generate a heading from an item in a consistent way for Markdown.
210
211		This ensures that references between documents are consistent.
212		"""
213		result = ""
214		heading = "#" * item.depth
215		level = format_level(item.level)
216		if item.heading:
217		text_lines = item.text.splitlines()
218		if item.header:
219		text_lines.insert(0, item.header)
220		# Level and Text
221		if settings.PUBLISH_HEADING_LEVELS:
222		standard = "{h} {lev} {t}".format(
223		h=heading, lev=level, t=text_lines[0] if text_lines else ""
224		)
225		else:
226		standard = "{h} {t}".format(
227		h=heading, t=text_lines[0] if text_lines else ""
228		)
229		attr_list = self.format_attr_list(item, True)
230		result = standard + attr_list
231		else:
232		uid = item.uid
233		if settings.ENABLE_HEADERS:
234		if item.header:
235		if to_html:
236		uid = "{h} <small>{u}</small>".format(h=item.header, u=item.uid)
237		else:
238		uid = "{h} _{u}_".format(h=item.header, u=item.uid)
239		else:
240		uid = "{u}".format(u=item.uid)
241
242		# Level and UID
243		if settings.PUBLISH_BODY_LEVELS:
244		standard = "{h} {lev} {u}".format(h=heading, lev=level, u=uid)
245		else:
246		standard = "{h} {u}".format(h=heading, u=uid)
247
248		attr_list = self.format_attr_list(item, True)
249		result = standard + attr_list
250		return result
251
252		def _lines_markdown(self, obj, **kwargs):
253		"""Yield lines for a Markdown report.
254
255		:param obj: Item, list of Items, or Document to publish
256		:param linkify: turn links into hyperlinks
257
258		:return: iterator of lines of text
259
260		"""
261		linkify = kwargs.get("linkify", False)
262		to_html = kwargs.get("to_html", False)
263		for item in iter_items(obj):
264		# Create iten heading.
265		complete_heading = self._generate_heading_from_item(item, to_html=to_html)
266		yield complete_heading
267
268		# Text
269		if item.text:
270		yield "" # break before text
271		yield from item.text.splitlines()
272
273		# Reference
274		if item.ref:
275		yield "" # break before reference
276		yield self.format_ref(item)
277
278		# Reference
279		if item.references:
280		yield "" # break before reference
281		yield self.format_references(item)
282
283		# Parent links
284	View Code Duplication	if item.links:
		0 ignored issues – show Duplication introduced 2024-01-10 14:52 UTC by Report Bug Copy Issue Report This code seems to be duplicated in your project. Loading history...
285		yield "" # break before links
286		items2 = item.parent_items
287		if settings.PUBLISH_CHILD_LINKS:
288		label = "Parent links:"
289		else:
290		label = "Links:"
291		links = self.format_links(items2, linkify)
292		label_links = self.format_label_links(label, links, linkify)
293		yield label_links
294
295		# Child links
296		if settings.PUBLISH_CHILD_LINKS:
297		items2 = item.find_child_items()
298		if items2:
299		yield "" # break before links
300		label = "Child links:"
301		links = self.format_links(items2, linkify)
302		label_links = self.format_label_links(label, links, linkify)
303		yield label_links
304
305		# Add custom publish attributes
306		if item.document and item.document.publish:
307		header_printed = False
308		for attr in item.document.publish:
309		if not item.attribute(attr):
310		continue
311		if not header_printed:
312		header_printed = True
313		yield ""
314		yield "\| Attribute \| Value \|"
315		yield "\| --------- \| ----- \|"
316		yield "\| {} \| {} \|".format(attr, item.attribute(attr))
317		yield ""
318
319		yield "" # break between items
320
321
322		def clean_link(uid):
323		"""Clean a UID for use in a link.
324
325		1. Strip leading # and spaces.
326		2. Only smallcaps are allowed.
327		3. Spaces are replaced with hyphens.
328		5. All other special characters are removed.
329		"""
330		uid = sub(r"^#\s", "", uid)
331		uid = uid.lower()
332		uid = uid.replace(" ", "-")
333		uid = sub("[^a-z0-9-]", "", uid)
334		return uid
335

doorstop-dev / doorstop

MarkdownPublisher.lines_index() A last analyzed 2025-06-26 14:29 UTC

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like

MarkdownPublisher.lines_index() A
last analyzed 2025-06-26 14:29 UTC