Debugging rtems-docs Sphinx issue

[Gedare Bloom]

On Wed, Feb 3, 2021 at 11:51 AM Ryan Long <ryan.long at oarcorp.com> wrote:

> Gedare,
>
>
>
> I applied your patch, but it still isn’t working for me. The error is the
> same in the console output and config.log.
>
> The ./waf configure command that I’m running is
>
> ./waf configure --prefix='`pwd`' –pdf
>
>
>

I get a different error using this command line, but it passes the bibtex
part. So I'm not sure.

I don’t know if that could be part of the issue.
>
>
>
> Thanks,
>
> Ryan
>
>
>
> *From:* Gedare Bloom <gedare at rtems.org>
> *Sent:* Wednesday, February 3, 2021 11:28 AM
> *To:* Ryan Long <ryan.long at oarcorp.com>
> *Cc:* devel at rtems.org
> *Subject:* Re: Debugging rtems-docs Sphinx issue
>
>
>
> Hi Ryan,
>
>
>
>
>
> On Tue, Feb 2, 2021 at 2:53 PM Ryan Long <ryan.long at oarcorp.com> wrote:
>
> Hi,
>
>
>
> I’m working on https://devel.rtems.org/ticket/4229#ticket .  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/waf.py
>
>
>
> contents.rst appears to be something generated dynamically by that waf.py
> in check_sphinx_extension, so that is not something you can test
> independently.
>
>
>
> I tried adding the recommended configuration settings to each of the
> conf.py 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:
>
>
>
> err:
> Extension error:
> You must configure the bibtex_bibfiles setting
>
> So our waf.py 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 conf.py will bring no joy. That said, we should include that
> bibtex_bibfiles in our conf.py, 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
> contents.rst
>
> 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']" > conf.py
>
> sphinx-build -b html -D extensions=sphinxcontrib.bibtex -c . . out
> contents.rst
>
>
>
> So I made the check rule dynamically create refs.bib and conf.py 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/conf.py file.
> Please try out the patch I just sent.
>
>
>
> Thanks,
>
> Gedare
>
>
>
> Thanks,
>
> Ryan
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20210203/42e10f73/attachment-0001.html>