adding own document classes creates error

[Gatherer]

Describe the bug

I have updated a company template to Sphinx 5.3.0. While testing the updated setup I noticed that I can not use the class anymore. Before the update we used a patched 2.1.2 version. There it was possible to use the class directly in latex_documents

latex_documents = [
    (root_doc,
    'test.tex',
    u'test Documentation',
    u'test',
    'mymanual'),
]

but in 5.3 or 6.1.2 it creates an error \normalsize. This error is usually thrown if the document class is not set up correct.

The use of the latex.tex_t template \documentclass[<%= papersize %>,<%= pointsize %><%= classoptions %>]{<%= wrapperclass.replace('sphinx', 'my') %>} together with using the default class works

latex_documents = [
    (root_doc,
    'test.tex',
    u'test Documentation',
    u'test',
    'manual'),
]

works.

But is this the correct way?

How to Reproduce

I have created a minimal example repository to reproduce it link. In this example I renewed the command sphinxtableofcontents.

The repository has two branches main_class and main_class_tex_t. With these two branches the two versions can be reproduced.

Environment Information

Platform:              Linux Mint 20.3
Python version:        3.8.10

I used a venv. The venv scripts are added in additional content part.

Sphinx extensions

extensions = [
    'sphinx.ext.intersphinx',
    'sphinx.ext.autodoc',
    'sphinx.ext.mathjax',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinxcontrib.bibtex',
    'sphinxcontrib.scalebybuilder',
    'sphinxcontrib.globalsubs',
    'sphinxcontrib.wavedrom',
    'sphinxcontrib.inkscapeconverter'
]

Additional context

Sphinx build logs: build_log_main.log build_log_main_class.log build_log_main_class_tex_t.log

Venv installation logs: venv_log_main.log venv_log_main_class.log venv_log_main_class_tex_t.log

What is the best way to handle it? Is it supported to create own .cls files? Do I miss documentations? Are there more in formations needed?

[jfbu]

Thanks for report. A breaking change happend at Sphinx 3.0.0 via a13ec4f41, from PR #6969. It seems I approved the PR at that time but overlooked the change. Formerly the produced .tex file would contain on top \def\sphinxdocclass{report}. Since 3.0.0, in your setting if will contain \def\sphinxdocclass{mymanual}. The problem is that the sphinxmanual.cls file uses this \sphinxdoclass as the name of class to load. But your class itself loads sphinxmanual.cls. Somehow LaTeX does not complain about never ending cycle but ends up never loading report or another standard class. To fix this, insert in your mymanual.cls an extra line to define yourself \sphinxdocclass to be a reasonable LaTeX class:

\NeedsTeXFormat{LaTeX2e}[1995/12/01]
\ProvidesClass{mymanual}[2023/01/13 v1.0.0 MY Document class (Sphinx manual)]
\def\sphinxdocclass{report}
\LoadClassWithOptions{sphinxmanual}
.... more stuff ....

It does appear that this Sphinx 3.0.0 change was breaking but I can not take care of this further in immediate future, due to other tasks. Can you confirm above change fixes your problem?

[Gatherer]

The fix works for the latest version and Sphinx 5.3.0. I updated the Github example.

Due to Python requirements I am stuck at Sphinx 5.3.0. So the fix is fine for me. Thanks for the fast reply.

[CLargeron]

I have a similar issue. I want to use a company template class to Sphinx 6.2.1 It appears as: \def\sphinxdocclass{mytemplate}

The pagestyle of my own class is overrided by the sphinx pagestyle. This enhances a generation of the pdf but without the pagestyle of my own class. Is there a way to use our own class without getting the pagestyle from manual or howto sphinx class ?

[jfbu]

@CLargeron Does file mytemplate.cls itself load sphinxmanual or sphinxhowto? If not this is some other issue.

[CLargeron]

@CLargeron Does file mytemplate.cls itself load sphinxmanual or sphinxhowto? If not this is some other issue.

Indeed, it doesn't. I will create a new issue.