Markdown labels not compatible with Doxygen

[henrik-garbergs]

Hi! When I publish the REQ document that's included with doorstop, i.e. when I run doorstop publish REQ REQ.md I get the following result:

# 1.0 Overview {#REQ018 }
## 1.1 Introduction <small>REQ019</small> {#REQ019 }
...

It would be possible to link to these chapters from other files parsed by Doxygen if it wasn't for the the space between REQ018 and "}". Is this done on purpose in the Doorstop markdown publish or would it be okay if I changed it to work better with Doxygen, i.e. by removing the space?

[henrik-garbergs]

The code looks like this, in doorstop/core/publisher.py:

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

If I just change {{#{u} }} to {{#{u}}} I get rid of the space in the label. I have to update some unit tests for publisher also, but that's easy. Would this be okay to do as a Pull Request?

[jacebrowning]

Yeah, I'm not totally sure why that space is there. We'll want to confirm this change doesn't break any of the other export formats.

[henrik-garbergs]

The suggested code change is located in a function called publisher.py::_format_md_attr_list which is only called from publisher.py::_lines_markdown. This function is called when publishing .md-files, which seems fine, and it is also called when HTML files are published. For HTML, the attribute "linkify" isn't set, and because of that _format_md_attr_list will return '' instead of the markdown-formatted string. So from a code walkthrough perspective it looks okay to change this, it will only affect the markdown publication.

I also made a check in practice: I ran the unit tests with and without the code change. The published text and HTML files where not changed:

diff doorstop/core/tests/files/published.txt ../doorstop_ref/doorstop/core/tests/files/published.txt
diff doorstop/core/tests/files/published2.txt ../doorstop_ref/doorstop/core/tests/files/published2.txt
diff doorstop/core/tests/files/published.html ../doorstop_ref/doorstop/core/tests/files/published.html
diff doorstop/core/tests/files/published2.html ../doorstop_ref/doorstop/core/tests/files/published2.html

The .md files were changed as expected:

diff doorstop/core/tests/files/published2.md ../doorstop_ref/doorstop/core/tests/files/published2.md
1c1
< ### 1.2.3 REQ001 {#REQ001}
---
> ### 1.2.3 REQ001 {#REQ001 }
14c14
< ## 1.4 REQ003 {#REQ003}
---
> ## 1.4 REQ003 {#REQ003 }
22c22
< ## 1.5 REQ006 {#REQ006}
---
> ## 1.5 REQ006 {#REQ006 }
31c31
< ## 1.6 REQ004 {#REQ004}
---
> ## 1.6 REQ004 {#REQ004 }
35c35
< ## 2.1 Plantuml <small>REQ002</small> {#REQ002}
---
> ## 2.1 Plantuml <small>REQ002</small> {#REQ002 }
57c57
< ## 2.1 REQ2-001 {#REQ2-001}
---
> ## 2.1 REQ2-001 {#REQ2-001 }

diff doorstop/core/tests/files/published.md ../doorstop_ref/doorstop/core/tests/files/published.md
1c1
< ### 1.2.3 REQ001 {#REQ001}
---
> ### 1.2.3 REQ001 {#REQ001 }
14c14
< ## 1.4 REQ003 {#REQ003}
---
> ## 1.4 REQ003 {#REQ003 }
22c22
< ## 1.5 REQ006 {#REQ006}
---
> ## 1.5 REQ006 {#REQ006 }
31c31
< ## 1.6 REQ004 {#REQ004}
---
> ## 1.6 REQ004 {#REQ004 }
35c35
< ## 2.1 Plantuml <small>REQ002</small> {#REQ002}
---
> ## 2.1 Plantuml <small>REQ002</small> {#REQ002 }
59c59
< ## 2.1 REQ2-001 {#REQ2-001}
---
> ## 2.1 REQ2-001 {#REQ2-001 }

Are there more checks we should do, or is this enough testing for creating a pull request?