Debugging rtems-docs Sphinx issue

Gedare Bloom gedare at
Wed Feb 3 17:27:35 UTC 2021

Hi Ryan,

On Tue, Feb 2, 2021 at 2:53 PM Ryan Long <ryan.long at> wrote:

> Hi,
> I’m working on .  The
> following command is being issued:
> /home/rlong/nta-workspace/nta-docs/sphinx/bin/sphinx-build -b html -D
> extensions=sphinxcontrib.bibtex -C . out contents.rst ->
> If I run this with the “->” at the end, I get “bash: syntax error near
> unexpected token `newline'” as the erro message. If I run it without the
> arrow,
> It prints out the usage, and it says “sphinx-build: error: cannot find
> files ['contents.rst']”.

That -> is not valid bash syntax. I guess that is something out of the waf
error logging. You can see where these checks are built in common/

contents.rst appears to be something generated dynamically by that
in check_sphinx_extension, so that is not something you can test

> I tried adding the recommended configuration settings to each of the
> files as sphinxcontrib-bibtex’s documentation recommended, and
> I added “master_doc = 'contents'” to each of them as well based on the
> warning message from config.log. Neither had any effect.

I think the master_doc thing is unrelated.

> Does anyone know how to fix this?

It looks like the important part is actually this:

Extension error:
You must configure the bibtex_bibfiles setting

So our that checks the sphinxcontrib.bibtex extension does not pass
through the bibtex_bibfiles setting.

Since that check uses the -C flag, the config file doesn't get read, so
modifying will bring no joy. That said, we should include that
bibtex_bibfiles in our, so I add that in a separate patch.

You can create a file contents.rst by hand and put in it the same:
.. COMMENT sphinx test

then you can run
$ sphinx-build -b html -D extensions=sphinx.ext.autodoc -C . out
for example

Unfortunately, I can't seem to figure out how to pass the bibtex_bibfiles
list to the command line. Everything I tried ends up parsing it into
individual characters, e.g.,
$ touch refs.bib
$ sphinx-build -b html -D extensions=sphinxcontrib.bibtex -D
bibtex_bibfiles=refs.bib -C . out contents.rst

WARNING: could not open bibtex file /mnt/devel/rtems/rtems-docs/build/r.
WARNING: could not open bibtex file /mnt/devel/rtems/rtems-docs/build/e.
WARNING: could not open bibtex file /mnt/devel/rtems/rtems-docs/build/f.
WARNING: could not open bibtex file /mnt/devel/rtems/rtems-docs/build/s.
then it dies because it can't open .

What I could get to work is to create a minimal config file and pass that:
$ echo "bibtex_bibfiles = ['refs.bib']" >
sphinx-build -b html -D extensions=sphinxcontrib.bibtex -c . . out

So I made the check rule dynamically create refs.bib and within the
testbuild directory. It might be more elegant to figure out how to pass the
_list_ that contains refs.bib in the command line -D version, but this
seemed to work.

I also added the bibtex_bibfiles setting to our common/ file. Please
try out the patch I just sent.


> Thanks,
> Ryan
> _______________________________________________
> devel mailing list
> devel at
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the devel mailing list