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