![[RTEMS Logo]](/images/logo.png){kind=logo}
Opened on 12/24/18 at 22:46:14
Closed on 02/06/19 at 21:30:22
#3669 closed defect (fixed)
rtems-docs.git does not build with Sphinx 1.8.2 and 1.8.3
| Reported by: | Chris Johns | Owned by: | Amar Takhar |
|---|---|---|---|
| Priority: | high | Milestone: | 5.1 |
| Component: | doc | Version: | 5 |
| Severity: | critical | Keywords: | |
| Cc: | Blocked By: | ||
| Blocking: |
Description
The docs do not build with Sphinx 1.8. Recent posts indicate some changes to support unicode indexes via xindy have caused this and the solution being discussed is to use the generate Makefile ...
https://github.com/rtfd/readthedocs.org/issues/4454
The need to use the Makefile is debatable however what it contains is important as it defines what needs to happen.
This recent issue can be seen in the Tex generated file for the User Manual (user.tex). It contains:
\item[{Waf\index{Waf@\spxentry{Waf}|spxpagem}\phantomsection\label{\detokenize{glossary/index:term-waf}}}] \leavevmode
Waf build system. For more information see \sphinxurl{http://www.waf.io/}
Our current build uses pdflatex directly and there is an error as spxpagem is not defined.
If you inspect a version 1.8 generated Makefile the command latexmk is used. This wraps the PDF generation so the correct number of passes are performed. Using this tool should be considered.
The Makefile contains:
export XINDYOPTS = -L english -C utf8 -M sphinx.xdy
The sphinx.xdy contains the needed spxpagem. I can only conclude sphinx needs to be built with xindy because the reference is always generated.
The problem for building FreeBSD is xindy is not an available command.
Change History (9)
comment:1 Changed on 12/25/18 at 00:11:19 by Amar Takhar
| Owner: | set to Amar Takhar |
|---|---|
| Status: | new → accepted |
comment:2 Changed on 12/26/18 at 18:52:50 by Joel Sherrill
FWIW I tried two CentOS 7 computers with Sphinx 1.8. Neither gets anywhere close to this point. Neither even creates a Makefile in the build tree. They both fail immediately with this:
joel@devel rtems-docs]$ ./waf Waf: Entering directory `/home/joel/rtems-work/rtems-docs/build' Waf: Leaving directory `/home/joel/rtems-work/rtems-docs/build' invalid number of source/target for bld(posted=True, target=[/home/joel/rtems-work/rtems-docs/build/user/latex/capt-of.sty, /home/joel/rtems-work/rtems-docs/build/user/latex/eqparbox.sty, /home/joel/rtems-work/rtems-docs/build/user/latex/environ.sty, /home/joel/rtems-work/rtems-docs/build/user/latex/ifplatform.sty, /home/joel/rtems-work/rtems-docs/build/user/latex/trimspaces.sty, /home/joel/rtems-work/rtems-docs/build/user/latex/slantsc.sty, /home/joel/rtems-work/rtems-docs/build/user/latex/upquote.sty, /home/joel/rtems-work/rtems-docs/build/user/latex/rtemsextrafonts.sty], idx=1, meths=['process_subst', 'process_rule', 'process_source'], source=['../common/latex/capt-of.sty', '../common/latex/eqparbox.sty', '../common/latex/environ.sty', '../common/latex/ifplatform.sty', '../common/latex/trimspaces.sty', '../common/latex/slantsc.sty', '../common/latex/upquote.sty'], path=/home/joel/rtems-work/rtems-docs/user, is_copy=True, features=['subst']) in /home/joel/rtems-work/rtems-docs/user
Both have a texlive install from around 20 Nov 2018. There is nothing much in the build/ directory after running waf configure and waf.
[joel@devel rtems-docs]$ find build -type f build/c4che/build.config.py build/c4che/_cache.py build/config.log build/.lock-waf_linux2_build
comment:3 Changed on 01/03/19 at 11:37:22 by Sebastian Huber
On openSUSE 15.0 I use a sphinx 1.8.1 with Python 3 and it works. I don't have a xindy tool installed.
comment:4 Changed on 01/03/19 at 11:51:00 by Sebastian Huber
I updated to sphinx 1.8.2 and 1.8.3. On both versions I experience the reported issue, e.g.
cd build/user/latex
pdflatex -shell-escape user.tex
...
[182] [183]
! Undefined control sequence.
<argument> \spxpagem
l.88 ...ecture}, \hyperindexformat{\spxpagem}{181}
?
comment:5 Changed on 01/03/19 at 11:51:21 by Sebastian Huber
| Summary: | rtems-docs.git does not build with Sphinx 1.8 → rtems-docs.git does not build with Sphinx 1.8.2 and 1.8.3 |
|---|
comment:6 Changed on 01/07/19 at 05:31:20 by Chris Johns
I suspect all future versions will behave the same way.
comment:7 Changed on 02/05/19 at 09:35:41 by Chris Johns
For FreeBSD we need to wait until a texlive update. This bug is tracking the progress:
comment:8 Changed on 02/06/19 at 02:59:17 by Chris Johns
With the help of the sphinx project I have resolved the issue. The issue in github is:
I will be working on a patch to sort this out.
comment:9 Changed on 02/06/19 at 21:30:22 by Chris Johns <chrisj@…>
| Resolution: | → fixed |
|---|---|
| Status: | accepted → closed |
In [changeset:"a3b0a40880c80dec607377b15d6a9d2223e8f9e3/rtems-docs" a3b0a40/rtems-docs]:
I'll sort this out, I've been aware this change was going to happen for a while now but since FreeBSD ports only has Sphinx 1.6.5 I haven't hit it yet.