Debugging rtems-docs Sphinx issue

[Gedare Bloom]

On Wed, Feb 3, 2021 at 1:04 PM Joel Sherrill <joel at rtems.org> wrote:
>
>
>
> 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 pushed my patch. Ryan, let me know if you still can't build the docs.

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