Debugging rtems-docs Sphinx issue

[Joel Sherrill]

On Wed, Feb 3, 2021 at 1:55 PM Gedare Bloom <gedare at rtems.org> wrote:

>
> 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.
>

As a general rule, don't use the source directory as the prefix. I usually
install to some temporary directory like /tmp/rtemsdocs-XXX.

Ryan's install of Sphinx is from this week AFAIK so it could be something
that has broken quite recently.


>
> 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
>>
>> _______________________________________________
> 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/6c93c6e5/attachment.html>