[RTEMS Project] #3669: rtems-docs.git does not build with Sphinx 1.8

[RTEMS trac]

#3669: rtems-docs.git does not build with Sphinx 1.8
--------------------------+--------------------
  Reporter:  Chris Johns  |      Owner:  (none)
      Type:  defect       |     Status:  new
  Priority:  high         |  Milestone:  5.1
 Component:  doc          |    Version:  5
  Severity:  critical     |   Keywords:
Blocked By:               |   Blocking:
--------------------------+--------------------
 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.

--
Ticket URL: <http://devel.rtems.org/ticket/3669>
RTEMS Project <http://www.rtems.org/>
RTEMS Project