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


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


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 Dec 25, 2018 at 12:11:19 AM by Amar Takhar

Owner: set to Amar Takhar
Status: newaccepted

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.

comment:2 Changed on Dec 26, 2018 at 6:52:50 PM 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

comment:3 Changed on Jan 3, 2019 at 11:37:22 AM 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 Jan 3, 2019 at 11:51:00 AM 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 Jan 3, 2019 at 11:51:21 AM by Sebastian Huber

Summary: rtems-docs.git does not build with Sphinx 1.8rtems-docs.git does not build with Sphinx 1.8.2 and 1.8.3

comment:6 Changed on Jan 7, 2019 at 5:31:20 AM by Chris Johns

I suspect all future versions will behave the same way.

comment:7 Changed on Feb 5, 2019 at 9:35:41 AM by Chris Johns

For FreeBSD we need to wait until a texlive update. This bug is tracking the progress:


comment:8 Changed on Feb 6, 2019 at 2:59:17 AM 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 Feb 6, 2019 at 9:30:22 PM by Chris Johns <chrisj@…>

Resolution: fixed
Status: acceptedclosed

In a3b0a40/rtems-docs:

Fix building with Sphinx 1.8 and later.

  • Provide the pytnon.ist file for makeindex.
  • Add support for xelatex building so we can switch if we want too.

Closes #3669

Note: See TracTickets for help on using tickets.