Skip to content

Commit 494824a

Browse files
gtjosephgtjoseph
committed
astxml2markdown.xslt: Fix processing of "note" and "warning"
Admonitions used inside lists were throwing off the list rendering and making a mess. * Changed to the pymarkdown-blocks style admonitions which use `/// <admonition>` and, more importantly, use a closing delimiter of `///`. * Added blank lines before every list item to get around another issue where list indentation was getting reset. * Fixed indentation in example blocks. Resolves: #65
1 parent 13cd5da commit 494824a

File tree

3 files changed

+69
-29
lines changed

3 files changed

+69
-29
lines changed

‎requirements.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,5 @@ mkdocs-material==9.5.6
55
mkdocs-material-extensions==1.3.1
66
mkdocs-minify-plugin==0.8.0
77
mkdocs-table-reader-plugin==2.1.0
8-
lxml==4.9.3
8+
lxml==5.1.0
99
pymdown-extensions==10.4

‎utils/astxml2markdown.py‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,17 @@
3535

3636
class FormatExample(etree.XSLTExtension):
3737
def __init__(self):
38-
self.replre = re.compile(r'^\s+')
38+
# We need to preserve blank lines while stripping leading whitespace
39+
# so we mark them with '<>', then remove leading whitespace
40+
# and then remove the '<>' markers.
41+
self.replre1 = re.compile(r'^\s*$', re.MULTILINE)
42+
self.replre2 = re.compile(r'^\s+', re.MULTILINE)
43+
self.replre3 = re.compile(r'^<>', re.MULTILINE)
3944

4045
def execute(self, context, self_node, input_node, output_parent):
41-
newtext = re.sub(self.replre, '', input_node.text)
46+
newtext = re.sub(self.replre1, '<>', input_node.text)
47+
newtext = re.sub(self.replre2, '', newtext)
48+
newtext = re.sub(self.replre3, '', newtext)
4249
newnode = deepcopy(input_node)
4350
newnode.text = newtext
4451
output_parent.append( newnode )

‎utils/astxml2markdown.xslt‎

Lines changed: 59 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,18 @@
11
<?xml version="1.0"?>
22
<xsl:stylesheet version="1.0"
33
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
4-
xmlns:ast="ast" extension-element-prefixes="ast"
4+
xmlns:ast="ast"
5+
xmlns:str="http://exslt.org/strings"
6+
extension-element-prefixes="ast str"
57
>
8+
69
<xsl:output method="text" omit-xml-declaration="yes" indent="no"/>
710

811
<xsl:variable name="smallcase" select="'abcdefghijklmnopqrstuvwxyz'" />
912
<xsl:variable name="uppercase" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZ'" />
1013

14+
<xsl:variable name="tabsize" select="'4'" />
1115
<xsl:variable name="bulletchar" select="'*'" />
12-
<xsl:variable name="bulletindent" select="' '" />
1316

1417
<xsl:template match="text()"/>
1518

@@ -661,11 +664,10 @@ the XML again with the full descriptions, and forms bulleted lists.
661664
<xsl:template match="info">
662665
<xsl:param name="bulletlevel"/>
663666
<xsl:param name="returntype"/>
664-
<xsl:value-of select="concat(substring($bulletindent, 0, $bulletlevel * 4 + 1), $bulletchar)"/>
665-
<xsl:text> *Technology: </xsl:text>
666-
<xsl:value-of select="@tech"/>
667-
<xsl:text>*&lt;br&gt;</xsl:text>
668-
<xsl:text>&#10;</xsl:text>
667+
<xsl:text>
668+
</xsl:text>
669+
<xsl:value-of select="str:padding($bulletlevel * $tabsize, ' ')"/>
670+
<xsl:value-of select="concat('* __Technology: ', @tech, '__&#10;')"/>
669671
<xsl:apply-templates>
670672
<xsl:with-param name="returntype">single</xsl:with-param>
671673
<xsl:with-param name="bulletlevel" select="$bulletlevel + 1"/>
@@ -695,8 +697,10 @@ the XML again with the full descriptions, and forms bulleted lists.
695697

696698
<xsl:template match="parameter">
697699
<xsl:param name="bulletlevel"/>
698-
<xsl:value-of select="concat(substring($bulletindent, 0, $bulletlevel * 4 + 1), $bulletchar, ' ')"/>
699-
<xsl:value-of select="@name"/>
700+
<xsl:text>
701+
</xsl:text>
702+
<xsl:value-of select="str:padding($bulletlevel * $tabsize, ' ')"/>
703+
<xsl:text>* `</xsl:text><xsl:value-of select="@name"/><xsl:text>`</xsl:text>
700704
<xsl:choose>
701705
<xsl:when test="para">
702706
<xsl:text> - </xsl:text>
@@ -717,7 +721,10 @@ the XML again with the full descriptions, and forms bulleted lists.
717721
<xsl:template match="argument">
718722
<xsl:param name="bulletlevel"/>
719723
<xsl:param name="separator">,</xsl:param>
720-
<xsl:value-of select="concat(substring($bulletindent, 0, $bulletlevel * 4 + 1), $bulletchar, ' ')"/>
724+
<xsl:text>
725+
</xsl:text>
726+
<xsl:value-of select="str:padding($bulletlevel * $tabsize, ' ')"/>
727+
<xsl:text>* </xsl:text>
721728
<xsl:if test="@required='true' or @required='yes'">
722729
<xsl:text>**</xsl:text>
723730
</xsl:if>
@@ -804,20 +811,32 @@ be displayed.
804811

805812
<xsl:template match="note">
806813
<xsl:param name="returntype"/>
807-
<xsl:text>!!! note&#10; </xsl:text>
808-
<xsl:apply-templates select="para">
809-
<xsl:with-param name="returntype" select="$returntype"/>
810-
</xsl:apply-templates>
811-
<xsl:text>&#10;</xsl:text>
814+
<xsl:param name="bulletlevel"/>
815+
<xsl:text>
816+
</xsl:text>
817+
<xsl:value-of select="str:padding($bulletlevel * $tabsize, ' ')"/>
818+
<xsl:text>/// note
819+
</xsl:text>
820+
<xsl:value-of select="normalize-space(.)"/>
821+
<xsl:text>
822+
///
823+
824+
</xsl:text>
812825
</xsl:template>
813826

814827
<xsl:template match="warning">
815828
<xsl:param name="returntype"/>
816-
<xsl:text>!!! warning&#10; </xsl:text>
817-
<xsl:apply-templates select="para">
818-
<xsl:with-param name="returntype" select="$returntype"/>
819-
</xsl:apply-templates>
820-
<xsl:text>&#10;</xsl:text>
829+
<xsl:param name="bulletlevel"/>
830+
<xsl:text>
831+
</xsl:text>
832+
<xsl:value-of select="str:padding($bulletlevel * $tabsize, ' ')"/>
833+
<xsl:text>/// warning
834+
</xsl:text>
835+
<xsl:value-of select="normalize-space(.)"/>
836+
<xsl:text>
837+
///
838+
839+
</xsl:text>
821840
</xsl:template>
822841

823842
<xsl:template match="variablelist">
@@ -829,7 +848,10 @@ be displayed.
829848

830849
<xsl:template match="variable">
831850
<xsl:param name="bulletlevel"/>
832-
<xsl:value-of select="concat(substring($bulletindent, 0, $bulletlevel * 4 + 1), $bulletchar, ' ')"/>
851+
<xsl:text>
852+
</xsl:text>
853+
<xsl:value-of select="str:padding($bulletlevel * $tabsize, ' ')"/>
854+
<xsl:text>* </xsl:text>
833855
<xsl:value-of select="translate(@name, $smallcase, $uppercase)"/>
834856
<xsl:choose>
835857
<xsl:when test="para">
@@ -845,7 +867,10 @@ be displayed.
845867
<xsl:choose>
846868
<xsl:when test="value">
847869
<xsl:for-each select="value">
848-
<xsl:value-of select="concat(substring($bulletindent, 0, ($bulletlevel + 1) * 4 + 1), $bulletchar, ' ')"/>
870+
<xsl:text>
871+
</xsl:text>
872+
<xsl:value-of select="str:padding(($bulletlevel + 1) * $tabsize, ' ')"/>
873+
<xsl:text>* </xsl:text>
849874
<xsl:value-of select="translate(@name, $smallcase, $uppercase)"/>
850875
<xsl:choose>
851876
<xsl:when test="string-length(@default) &gt; 0">
@@ -871,8 +896,10 @@ be displayed.
871896

872897
<xsl:template match="enum">
873898
<xsl:param name="bulletlevel"/>
874-
<xsl:value-of select="concat(substring($bulletindent, 0, $bulletlevel * 4 + 1), $bulletchar, ' ')"/>
875-
<xsl:value-of select="@name"/>
899+
<xsl:text>
900+
</xsl:text>
901+
<xsl:value-of select="str:padding($bulletlevel * $tabsize, ' ')"/>
902+
<xsl:text>* `</xsl:text><xsl:value-of select="@name"/><xsl:text>`</xsl:text>
876903
<xsl:choose>
877904
<xsl:when test="para">
878905
<xsl:text> - </xsl:text>
@@ -881,7 +908,8 @@ be displayed.
881908
</xsl:apply-templates>
882909
</xsl:when>
883910
<xsl:otherwise>
884-
<xsl:text>&#10;</xsl:text>
911+
<xsl:text>
912+
</xsl:text>
885913
</xsl:otherwise>
886914
</xsl:choose>
887915
<!--
@@ -897,9 +925,11 @@ be displayed.
897925
<xsl:with-param name="bulletlevel" select="$bulletlevel + 1"/>
898926
</xsl:apply-templates>
899927
<xsl:apply-templates select="note">
928+
<xsl:with-param name="bulletlevel" select="$bulletlevel + 1"/>
900929
<xsl:with-param name="returntype">single</xsl:with-param>
901930
</xsl:apply-templates>
902931
<xsl:apply-templates select="warning">
932+
<xsl:with-param name="bulletlevel" select="$bulletlevel + 1"/>
903933
<xsl:with-param name="returntype">single</xsl:with-param>
904934
</xsl:apply-templates>
905935
</xsl:template>
@@ -913,7 +943,10 @@ be displayed.
913943

914944
<xsl:template match="option">
915945
<xsl:param name="bulletlevel"/>
916-
<xsl:value-of select="concat(substring($bulletindent, 0, $bulletlevel * 4 + 1), $bulletchar, ' ')"/>
946+
<xsl:text>
947+
</xsl:text>
948+
<xsl:value-of select="str:padding($bulletlevel * $tabsize, ' ')"/>
949+
<xsl:text>* </xsl:text>
917950
<xsl:value-of select="@name"/>
918951
<xsl:if test="argument">
919952
<xsl:text>`( </xsl:text>

0 commit comments

Comments
 (0)