search

vovkos / doxyrest

A compiler from Doxygen XML to reStructuredText -- hence, the name. It parses XML databases generated by Doxygen and produces reStructuredText for the Python documentation generator Sphinx.
MIT License
306 stars 23 forks source link

Table generation with an extra blank line #19

Closed ghochee closed 5 years ago

ghochee commented 5 years ago

[edit: code blocks for readability]

The following doxygen c++ comment

/// | A | B | A && B |
/// |---|---|--------|
/// | F | F |   F    |
/// | F | T |   F    |
/// | T | F |   F    |
/// | T | T |   T    |

generates the following xml

<para><table rows="5" cols="3"><row>
<entry thead="yes"><para>A  </para>
</entry><entry thead="yes"><para>B  </para>
</entry><entry thead="yes"><para>A &amp;&amp; B   </para>
</entry></row>
<row>
<entry thead="no"><para>F  </para>
</entry><entry thead="no"><para>F  </para>
</entry><entry thead="no"><para>F   </para>
</entry></row>
<row>
...

doxyrest produces

=  =  ====== 
A  B  A && B 
=  =  ====== 

F  F  F      
F  T  F      
T  F  F      
T  T  T      
=  =  ======

There is an extra blank line after the table header line which breaks the rendering.

I'll be happy to fix it if you think this doesn't require complex surgery.

vovkos commented 5 years ago

Good catch. Table implementation was contributed a while ago, before the major 2.0 redesign. Maybe, I introduced a regression while porting it -- or, more likely, it never was tested against tables with a header row.

In any case, the fix is pretty simple and should go to the formatDocBlock_table function.

Please send me a pull request with the fix and I will merge it.

Thank you!

ghochee commented 5 years ago

Thanks for the response, I am in the middle of a time consuming transition, will send you a PR after next week.

ghochee commented 5 years ago

Hello @vovkos ,

I am having some difficulty building doxyrest from the source. I am facing the following problems:

I built and installed expat library on a systemwide path I built and installed axl library and headers on a systemwide path ls -l libaxl -rw-r--r-- 1 root root 864058 Jul 7 11:43 libaxl_core.a -rw-r--r-- 1 root root 94320 Jul 7 11:43 libaxl_cry.a -rw-r--r-- 1 root root 178338 Jul 7 11:43 libaxl_fsm.a -rw-r--r-- 1 root root 161982 Jul 7 11:43 libaxl_gui.a -rw-r--r-- 1 root root 481740 Jul 7 11:43 libaxl_io.a -rw-r--r-- 1 root root 19038 Jul 7 11:43 libaxl_lex.a -rw-r--r-- 1 root root 29612 Jul 7 11:43 libaxl_lua.a -rw-r--r-- 1 root root 39710 Jul 7 11:43 libaxl_xml.a -rw-r--r-- 1 root root 114960 Jul 7 11:43 libaxl_zip.a Note there is no libaxl. . AFAICT this is what is required by the doxyrest CMakeLists.txt file.

I think maybe the projects are too out of sync so thought of reaching out before attempting other more complicated things. Thanks in advance for your help on this.

vovkos commented 5 years ago

doxyrest_b is guaranteed to always be in sync -- that was the whole point of this "bundle". You can check CI build logs of the last commit to doxyrest_b here: https://travis-ci.org/vovkos/doxyrest_b

Also, there is absolutely no need to install axl to a systemwide path -- building everything from the doxyrest_b source tree is enough. The reason why build is failing on your machine is the lack of ragel. As you can see in your build log: 

    ragel is REQUIRED but NOT FOUND

Most modern Linux distros have ragel in official repos; on Mac OSX you can use homebrew to install ragel. Install ragel and then re-run cmake from the doxyrest_b build folder.

ghochee commented 5 years ago

Thanks, I'll set it up and send a PR in a bit.

ghochee commented 5 years ago

Vladimir, thanks for authoring doxyrest, I think it's extremely useful. Thanks also for the quick responses to my questions and for accepting the PR.

Cheers

vovkos commented 5 years ago

Hello Aditya, I'm really glad you find Doxyrest useful, hope it will help you in creating some great docs! Thank you for your kind words -- and for the fix, of course! Feel free to submit more :)