]> jfr.im git - irc/hexchat/documentation.git/commit
var:: to macro:: fixes sphinx-build v3.3+ warning
authorHoward Johnson <redacted>
Thu, 31 Dec 2020 04:21:49 +0000 (18:21 -1000)
committerHoward Johnson <redacted>
Thu, 31 Dec 2020 04:21:49 +0000 (18:21 -1000)
commit723f6be38c6b50272485f0443d14af7ac0c3916d
treed05d9720df7a122ffa3e45ebe8bfaeeff76a52a8
parent23c51f4c1d220786dc2379de6853a73912f07d4b
var:: to macro:: fixes sphinx-build v3.3+ warning

PROBLEM --------------------------------------------------------------
  Upgraded from sphinx-build v2 to v3.3.1.

  Then running:

    mkdir x                                             && cd x
    git clone https://github.com/hexchat/documentation  && cd documentation
    make clean && make html           # To build the html output files

  outputs a bunch of new WARNING messages, including these:

    $ make clean && make html
    sphinx-build -b html -d _build/doctrees   . _build/html
    Running Sphinx v3.3.1
    ...
    /home/howard/git-repos/hexchat/documentation/plugins.rst:579: WARNING: Error in declarator or parameters
    Invalid C declaration: Expected identifier in nested name. [error at 19]    <-- fixes these 12 warnings
      HEXCHAT_PRI_HIGHEST
      -------------------^

  (Plus 11 more warnings like this.)

SOLUTION --------------------------------------------------------------
  First note plugins.rst line 4:

    .. default-domain:: c     # this sets default domain to :c:*

  Next, https://bugs.python.org/issue40204 reports:

    "The C domain has been rewritten, with additional directives and roles.
    The existing ones are now more strict, resulting in new warnings."

    Correct usage for `.. var::` and `.. macro::` are documented here:
      https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html

  For comparision current hexchat built docs is at:
https://hexchat.readthedocs.io/en/latest/plugins.html#c.HEXCHAT_PRI_HIGHEST

  Note
    To rerun `make html` again, first `touch plugins.rst` or run `make clean`.

OTHER --------------------------------------------------------------
  I'm new to open source contributing. Appreciate any help.
  hwj@BridgeportContractor.com
plugins.rst