markstory / sphinxcontrib-phpdomain

A PHP domain for sphinx. Allows you to annotate PHP objects in your sphinx docs.
Other
19 stars 15 forks source link

Parse error must emit build warning #58

Closed mvorisek closed 1 year ago

mvorisek commented 1 year ago

Currently it seems all wrong input is silently accepted and all internal parse errors supressed.

Example rst:

.. php:class:: Scope

.. php:method:: simplify();

notice the ; at the method end. The ; should not be present, but when present, the rendered result is very off:

 <dl class="php method">
-<dt class="sig sig-object php" id="Scope::simplify">
-<span class="sig-prename descclassname"><span class="pre">Scope::</span></span>
-<span class="sig-name descname"><span class="pre">simplify</span></span>
-<span class="sig-paren">(</span><span class="sig-paren">)</span>
-<a class="headerlink" href="#Scope::simplify" title="Permalink to this definition">¶</a></dt>
+<dt class="sig sig-object php">
+<span class="sig-name descname"><span class="pre">simplify();</span></span></dt>
 <dd></dd></dl>

catching such typos manually is very hard.

Sphinx does support build warnings, example:

image

So I expect this extension to emit warning on wrong input as well.

Zero warnings can be then then easily asserted using CI.