sphinx-doc / sphinx-doc/sphinx

Unnumbered toctree has numbers in LaTeX output

Open
#8,087 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

builder:latex internals:toctree type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Consider this project

Project

.
├── conf.py
├── foo.rst
├── bar.rst
├── index.rst
└── index.rst

index.rst

Test
====

.. toctree::
    :numbered:
    :maxdepth: 2
    :caption: Numbered Toctree

    foo

.. toctree::
    :caption: Unnumbered Toctree

    bar

foo.rst

========
Numbered
========

Bravo
=====

Charlie
-------

bar.rst

==========
Unnumbered
==========

Bravo
=====

Charlie
-------

Output

On the HTML, everything is fine. The unnumbered toctree has unnumbered sections. It's perfect.

image

On the other hand, for LaTeX, the sections are still numbered:

image

Analysis

The latex visit_title method will always add a numbered section \section{foo}, but it should add an unnumbered \section*{foo}.

I guess this is a bug since the behavior should be the same on both outputs (html + latex).

Context

I am writing a programming course that generates a web documentation as well as a book. This book should have a frontmatter/mainmatter and backmatter. Of course, some sections in the backmatter should not be numbered.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the LaTeX writer's visit_title method identified in the issue, then reproduce the example with the numbered and unnumbered toctrees in both HTML and LaTeX. Done means sections under the unnumbered toctree remain unnumbered in LaTeX while the numbered toctree is unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
latex, python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.