Sphinx: The toctree ``:numbered:`` option has no effect in PDF

[jfbu]

Procedure to reproduce the problem

File index.rst

====================
Test Numbered Levels
====================

.. toctree::
   :numbered:

   page

File page.rst

==============
Top sectioning
==============

level 2 sectioning
==================

level 3 sectioning
------------------

level 4 sectioning
~~~~~~~~~~~~~~~~~~

level 5 sectioning
^^^^^^^^^^^^^^^^^^

Hello

Error logs / results

HTML output is numbered all the way, PDF via make latexpdf only down to level 3.

Expected results

PDF also obeys the :numbered: option, inclusive of its optional parameter.

Environment info

• OS: Mac
• Python version: 3.6.3
• Sphinx version: 1.6.3 and master

[tk0miya]

I have a plan (idea?) to restructure ToC structure of Sphinx in future. Personally, I and friends wrote a Japanese book for Sphinx beginners in this year. But current Sphinx can't represent prefaces and appendixes.
And I know some users uses Sphinx to write books and thesis. So it would be nice to enhance ToC tree structure for the purpose.

I don't know when we can modify it (1.8 or 2.x?). But I feel the modification is related with this. So I notice you my idea :-)

[jfbu]

Thanks for sharing your idea ;-)

Recently I needed to produce a pdf with appendices. I solved this via some bit of LaTeX hacking in particular some raw LaTeX.

In case people come across this, here is how it looks (I leave some extras for PDF bookmarks). But this is really a hack I needed to get the job done quickly, perhaps there is easier way.

latex_docclass = {'howto': 'article', 'manual': 'book'} # and we use 'manual' -> book class now

latex_elements = {
    # some other stuff, and

    'fncychap': '\\usepackage[Bjornstrup]{fncychap}',

    'preamble': r'''
\usepackage{bookmark}% for customization of PDF bookmarks
\makeatletter
\renewcommand{\sphinxtableofcontents}{% custom to control \pagestyle usage and page numbering
  \pagenumbering{roman}%
  \pagestyle{plain}%
  \begingroup
    \parskip \z@skip
    \pdfbookmark[1]{Table des matières}{MAINTOC}%
    \tableofcontents
  \endgroup
  \ifdefined\fancyhf\pagestyle{normal}\fi
}
\renewcommand{\thesection}{\@arabic\c@section}% for duration of introduction
\renewcommand\@chapapp[3]{}% LaTeX hack to get footers cleared initially
\@mainmatterfalse % and raw latex will be used after introduction to do \mainmatter, \thesection, \@chapapp
\let\oldmaketitle\maketitle
\def\maketitle{\bookmark[named=FirstPage, level=1]{Page de titre}%
               \oldmaketitle}%
\makeatother
''',

At bottom of the reST file which contains the document introduction:

.. raw:: latex

   \mainmatter
   \makeatletter
   \renewcommand{\thesection}{\thechapter.\@arabic\c@section}%
   \renewcommand{\@chapapp}{\chaptername}%
   \makeatother

and finally at bottom of last reST non-appendix file

.. raw:: latex

   \appendix

BTW, I know there is latex_appendices but I am not sure what it does ;-)

About support of :numbered: for LaTeX, it looks as if it is mainly a question of using suitable \setcounter{secnumdepth}. This can be done in preamble and again midway in document if needed (but then complications with things such as my PR #4311). For the case of :numbered: with no argument, secnumdepth should be set to 5. (Sphinx sets it by default to 2).

It seems the :numbered: option is used by the toctree collector to create numbered section nodes, but for LaTeX it is only a matter in simple cases to pass over a single number to latex writer ... not sure how to do this best, and then how to handle varying values of :numbered: argument across documents.

[tk0miya]

FYI:

BTW, I know there is latex_appendices but I am not sure what it does ;-)

As far as I read the code, it is simply concatenate documents after the main doctree. There are no special support to reference (like Appendix A) and layouting.

[TobiasWulf]

Hello all,

I figured out when you change the document class parameter latex_document from howto to manual so you switch from article to report class in latex, in the following the conf file attribute latex_appendices does exactly what was mentioned to wish to do. But headings from rst files start now from chapter down to section and so on.

The latex package titlesec is already included by sphinx you just have to edit your own chapter, section title formats and the documenting can begin :)

I did something like this in a sty file which I include in the latex customization before at keyword extrapackages with \RequirePackage.

Depending on that if you wish to generate html output too or not. Mention to turn it on or off
to include the headings etc. or only the toctrees from the index.rst file. True or False last parameter for latex_document attribute in conf file. I prefer to turn it off and adjust the file in a way that I got a similar styled output as in my latex document. So extra doc titles for Appendix and Bibliography which is handled different in html.

Solution for title formats in latex with titlesec:

% theme color
\definecolor{PaleBlue}{RGB}{94,137,193}
\newcommand{\ThemeColor}{PaleBlue}

%
% headings format (part copied from sphinx
% Augment the sectioning commands used to get our own font family in place,
% and reset some internal data items (\titleformat from titlesec package)
\titleformat{\chapter}{\Large\sffamily\bfseries}{\color{\ThemeColor}\thechapter}{1em}{\color{\ThemeColor}}[\vspace{-6.5mm}\docrule\color{TextBlack}]

\titleformat{\section}{\large\sffamily\bfseries}{\color{\ThemeColor}\thesection}{0.5em}{\color{\ThemeColor}}[\color{TextBlack}]
\titleformat{\subsection}{\sffamily\bfseries}{\color{\ThemeColor}\thesubsection}{0.5em}{\color{\ThemeColor}}[\color{TextBlack}]

\titleformat{\subsubsection}{\sffamily\bfseries}{\color{\ThemeColor}\thesubsubsection}{0.5em}{\color{\ThemeColor}}[\color{TextBlack}]

% By default paragraphs (and subsubsections) will not be numbered because
% sphinxmanual.cls and sphinxhowto.cls set secnumdepth to 2
\titleformat{\paragraph}{\sffamily\bfseries}{\color{\ThemeColor}\theparagraph}{0.5em}{\color{\ThemeColor}}[\color{TextBlack}]

\titleformat{\subparagraph}{\sffamily\bfseries}{\color{\ThemeColor}\thesubparagraph}{0.5em}{\color{\ThemeColor}}[\color{TextBlack}]

% title spacing left, before, after
\titlespacing{\chapter}{0.0mm}{0.0mm}{5.0mm}
\titlespacing{\section}{0.0mm}{5.0mm}{2.5mm}
\titlespacing{\subsection}{0.0mm}{4.6mm}{2.5mm}
\titlespacing{\subsubsection}{0.0mm}{4.0mm}{2.0mm}
\titlespacing{\paragraph}{0.0mm}{4.0mm}{2.0mm}
\titlespacing{\subparagraph}{0.0mm}{4.0mm}{1.0mm}

Kind regards,

Tobias

[TobiasWulf]

sorry, forgot the \docrule command

\newcommand{\docrule}{\color{\ThemeColor}{\rule{\textwidth}{0.2mm}}}

[TobiasWulf]

So one thing left. You have to comment out the appendix_file from any toctree if you run latexpdf and added file to latex_appendices to prevent double assign in the latex toc. Unfortunately a warning is raised that the appendix file is not bind in any toctree. What is true for html but not for latex. At the moment I have to comment the appendix part out in the index file when I run make latexpdf and comment in again for make html as not numbered toctree.