search

svenevs / exhale

Automatic C++ library api documentation generation: breathe doxygen in and exhale it out.
BSD 3-Clause "New" or "Revised" License
218 stars 51 forks source link

Warnings caused by missing newlines in exhale output #171

Closed emprice closed 2 years ago

emprice commented 2 years ago

I'm getting lots of warnings like the following when I build my docs:

/path/to/source/exhale/file_src_helpers.hh.rst:10: WARNING: Explicit markup ends without a blank line; unexpected unindent.

The file generated by exhale looks like this:

.. _file_src_helpers.hh:

File helpers.hh
===============

|exhale_lsh| :ref:`Parent directory <dir_src>` (``src``)

.. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS
Definition (``src/helpers.hh``)
-------------------------------

I think Sphinx just wants an empty line before that subheading "Definition". Looking at the exhale source, there are only 3 places where a line with the U+021B0 character is generated; one has that extra newline, and two don't. As a quick fix, I added another newline to the ones that didn't have it, but there could easily be something more subtle going on here.

I know it's just a warning, and the docs end up just fine either way. On the other hand, having a bunch of warnings that don't "mean" anything makes it much more difficult to pick out the ones I should actually fix.

Please let me know if I can help with debugging this.

svenevs commented 2 years ago

Thanks for reporting @emprice, this is definitely a bug! The tests don't really catch this scenario, but what you describe above should not be what is generated. Can you check that #172 fixes these warnings for you please? Assuming things are good I'll do a quick release :slightly_smiling_face:

emprice commented 2 years ago

I just regenerated my docs, and #172 does appear to fix all those spurious warnings for me. Thanks so much for the quick fix, @svenevs!

svenevs commented 2 years ago

Awesome, thanks for confirming! v0.3.5 is on pypi now :slightly_smiling_face: