From 611316f79b110e9915c10d09718b2f1543512f5b Mon Sep 17 00:00:00 2001 From: Fabio Utzig Date: Tue, 1 Dec 2020 18:20:25 -0300 Subject: [PATCH 1/2] Add support for \parblock parsing and rendering Add support for using the \parblock command from Doxygen: https://www.doxygen.nl/manual/commands.html#cmdparblock This command can be used to generate multiple paragraphs from simple text inside the section. It's most useful for grouping text in Doxygen aliases. Signed-off-by: Fabio Utzig --- breathe/parser/compound.py | 19 +++++++++ breathe/parser/compoundsuper.py | 66 ++++++++++++++++++++++++++++++ breathe/renderer/sphinxrenderer.py | 4 ++ 3 files changed, 89 insertions(+) diff --git a/breathe/parser/compound.py b/breathe/parser/compound.py index b08afcf9..53ab12bb 100644 --- a/breathe/parser/compound.py +++ b/breathe/parser/compound.py @@ -1050,12 +1050,31 @@ def buildChildren(self, child_, nodeName_): obj_ = supermod.docAnchorType.factory() obj_.build(child_) self.content.append(obj_) + elif child_.nodeType == Node.ELEMENT_NODE and nodeName_ == "parblock": + obj_ = supermod.docParBlockType.factory() + obj_.build(child_) + self.content.append(obj_) supermod.docParaType.subclass = docParaTypeSub # end class docParaTypeSub +class docParBlockTypeSub(supermod.docParBlockType): + + node_type = "docparblock" + + def __init__(self, para=None): + supermod.docParBlockType.__init__(self, para) + + def buildChildren(self, child_, nodeName_): + supermod.docParBlockType.buildChildren(self, child_, nodeName_) + + +supermod.docParBlockType.subclass = docParBlockTypeSub +# end class docParBlockTypeSub + + class docMarkupTypeSub(supermod.docMarkupType): node_type = "docmarkup" diff --git a/breathe/parser/compoundsuper.py b/breathe/parser/compoundsuper.py index 0c3e436e..c24e3619 100644 --- a/breathe/parser/compoundsuper.py +++ b/breathe/parser/compoundsuper.py @@ -5682,6 +5682,72 @@ def buildChildren(self, child_, nodeName_): # end class docCharType +class docParBlockType(GeneratedsSuper): + subclass = None + superclass = None + def __init__(self, mixedclass_=None, para=None): + if mixedclass_ is None: + self.mixedclass_ = MixedContainer + else: + self.mixedclass_ = mixedclass_ + if para is None: + self.para = [] + else: + self.para = para + def factory(*args_, **kwargs_): + if docParBlockType.subclass: + return docParBlockType.subclass(*args_, **kwargs_) + else: + return docParBlockType(*args_, **kwargs_) + factory = staticmethod(factory) + def get_para(self): return self.para + def set_para(self, para): self.para = para + def add_para(self, value): self.para.append(value) + def insert_para(self, index, value): self.para[index] = value + def export(self, outfile, level, namespace_='', name_='docParBlockType', namespacedef_=''): + showIndent(outfile, level) + outfile.write('<%s%s%s' % (namespace_, name_, namespacedef_ and ' ' + namespacedef_ or '', )) + self.exportAttributes(outfile, level, namespace_, name_='docParBlockType') + if self.hasContent_(): + outfile.write('>\n') + self.exportChildren(outfile, level + 1, namespace_, name_) + showIndent(outfile, level) + outfile.write('\n' % (namespace_, name_)) + else: + outfile.write('/>\n') + def exportAttributes(self, outfile, level, namespace_='', name_='docParBlockType'): + pass + def exportChildren(self, outfile, level, namespace_='', name_='docParBlockType'): + for para_ in self.para: + para_.export(outfile, level, namespace_, name_='para') + def hasContent_(self): + if ( + self.para + ): + return True + else: + return False + def build(self, node_): + attrs = node_.attributes + self.buildAttributes(attrs) + self.valueOf_ = '' + for child_ in node_.childNodes: + nodeName_ = child_.nodeName.split(':')[-1] + self.buildChildren(child_, nodeName_) + def buildAttributes(self, attrs): + pass + def buildChildren(self, child_, nodeName_): + if child_.nodeType == Node.ELEMENT_NODE and \ + nodeName_ == 'para': + obj_ = docParaType.factory() + obj_.build(child_) + obj_ = self.mixedclass_(MixedContainer.CategoryComplex, + MixedContainer.TypeNone, 'para', obj_) + self.para.append(obj_) + +# end class docParBlockType + + class docEmptyType(GeneratedsSuper): subclass = None superclass = None diff --git a/breathe/renderer/sphinxrenderer.py b/breathe/renderer/sphinxrenderer.py index 7c7b0f7c..45a7dc7e 100644 --- a/breathe/renderer/sphinxrenderer.py +++ b/breathe/renderer/sphinxrenderer.py @@ -1284,6 +1284,9 @@ def visit_docpara(self, node) -> List[Node]: return [nodes.paragraph("", "", *nodelist)] + def visit_docparblock(self, node) -> List[Node]: + return self.render_iterable(node.para) + def visit_docimage(self, node) -> List[Node]: """Output docutils image node using name attribute from xml as the uri""" @@ -1934,6 +1937,7 @@ def dispatch_memberdef(self, node) -> List[Node]: "docreftext": visit_docreftext, "docheading": visit_docheading, "docpara": visit_docpara, + "docparblock": visit_docparblock, "docimage": visit_docimage, "docurllink": visit_docurllink, "docmarkup": visit_docmarkup, From 11e6745692a774841797018834e8f98f1332486a Mon Sep 17 00:00:00 2001 From: Fabio Utzig Date: Tue, 1 Dec 2020 18:23:03 -0300 Subject: [PATCH 2/2] Add \parblock documentation page Signed-off-by: Fabio Utzig --- documentation/source/doxygen.rst | 8 ++++++++ examples/doxygen/.gitignore | 1 + examples/doxygen/Makefile | 7 +++++-- examples/doxygen/parblock.cfg | 11 +++++++++++ examples/doxygen/parblock.cpp | 24 ++++++++++++++++++++++++ 5 files changed, 49 insertions(+), 2 deletions(-) create mode 100644 examples/doxygen/parblock.cfg create mode 100644 examples/doxygen/parblock.cpp diff --git a/documentation/source/doxygen.rst b/documentation/source/doxygen.rst index bd11a7db..6e875adb 100644 --- a/documentation/source/doxygen.rst +++ b/documentation/source/doxygen.rst @@ -84,6 +84,14 @@ Par .. doxygenindex:: :path: ../../examples/doxygen/par/xml +Parblock +-------- + +.. cpp:namespace:: @ex_doxygen_parblock + +.. doxygenindex:: + :path: ../../examples/doxygen/parblock/xml + Overload -------- diff --git a/examples/doxygen/.gitignore b/examples/doxygen/.gitignore index 63ae4046..9dc1e0a4 100644 --- a/examples/doxygen/.gitignore +++ b/examples/doxygen/.gitignore @@ -18,6 +18,7 @@ mux overload page par +parblock pyexample qtstyle relates diff --git a/examples/doxygen/Makefile b/examples/doxygen/Makefile index 10278935..ff04bc1d 100644 --- a/examples/doxygen/Makefile +++ b/examples/doxygen/Makefile @@ -27,6 +27,7 @@ all: class/xml/index.xml \ relates/xml/index.xml \ author/xml/index.xml \ par/xml/index.xml \ + parblock/xml/index.xml \ overload/xml/index.xml \ example/xml/index.xml \ include/xml/index.xml \ @@ -49,7 +50,7 @@ all: class/xml/index.xml \ clean: rm -rf class define enum file func page relates author \ - par overload example include qtstyle jdstyle structcmd \ + par parblock overload example include qtstyle jdstyle structcmd \ autolink tag restypedef afterdoc template tag group diagrams \ memgrp docstring pyexample mux manual interface @@ -80,6 +81,9 @@ author/xml/index.xml: author.cpp author.cfg par/xml/index.xml: par.cpp par.cfg $(DOXYGEN) par.cfg +parblock/xml/index.xml: parblock.cpp parblock.cfg + $(DOXYGEN) parblock.cfg + overload/xml/index.xml: overload.cpp overload.cfg $(DOXYGEN) overload.cfg @@ -140,4 +144,3 @@ diagrams/xml/index.xml: diagrams_a.h diagrams_b.h diagrams_c.h diagrams_d.h diag ifneq ($(HAVE_DOT),) $(DOXYGEN) diagrams.cfg endif - diff --git a/examples/doxygen/parblock.cfg b/examples/doxygen/parblock.cfg new file mode 100644 index 00000000..0aa2cc59 --- /dev/null +++ b/examples/doxygen/parblock.cfg @@ -0,0 +1,11 @@ +PROJECT_NAME = "Parblock Command" +OUTPUT_DIRECTORY = parblock +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_RTF = NO +CASE_SENSE_NAMES = NO +INPUT = parblock.cpp +QUIET = YES +JAVADOC_AUTOBRIEF = YES +GENERATE_HTML = NO +GENERATE_XML = YES diff --git a/examples/doxygen/parblock.cpp b/examples/doxygen/parblock.cpp new file mode 100644 index 00000000..b845382f --- /dev/null +++ b/examples/doxygen/parblock.cpp @@ -0,0 +1,24 @@ +/*! \class Test15 + * Normal text. + * + * \par A paragraph followed by a paragraph block: + * \parblock + * Contents of the first paragraph in the block. + * + * New paragraph under the same heading. + * \endparblock + * + * \note + * This note consists of three paragraphs in a block. + * \parblock + * This is the first paragraph in the block. + * + * And this is the second paragraph in the block. + * + * And still a third paragraph in the block. + * \endparblock + * + * More normal text. + */ + +class Test15 {};