Consider adding a "guess" pseudo-language to the PygmentsBridge as a transitional aid for people converting large documents with mixed code literals.

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/15
• Originally reported by: Georg Brandl
• Originally created at: 2008-11-02T22:22:06.829

It would be useful to have an option that causes Sphinx to automatically create a TOC entry for every function, class, and method. (In the absence of this, tables of contents are of limited value).

According to our annual release cycle, this April is time for the major release. I think this schedule is good for the release. What do you think?

• Apr 10th:
  • Beta release (feature freeze)
  • call for translation
  • Create a new branch: 4.x and 4.0.x
    • 4.x will be used for develop 4.1
    • 4.0.x will be used for develop 4.0.0 (feature freezed)
• Apr 24th: final release

Any comments?

Note: issues marked as 4.0.0: https://github.com/sphinx-doc/sphinx/milestone/74

If Sphinx's LaTeX output gets too deeply-nested, I get the following error:

[13] [14]
Chapter 4.
[15]

! LaTeX Error: Too deeply nested.

I've found an item on the Docutils to-do list: http://docutils.sourceforge.net/docs/dev/todo.html indicating that this is something they're aware of, but have not yet fixed, but I'm wondering if this is something Sphinx can work around in the mean time.

In particular, the LaTeX "enumitem" package: http://www.tex.ac.uk/CTAN/macros/latex/contrib/enumitem/ has recently added support for list environments of any depth. I was wondering if Sphinx could make use of this package to allow nesting of chapters and code blocks to a higher number of levels, because when you start using code blocks with several levels of indentation, the nesting gets deep quickly, and standard LaTeX maxes out somewhere around 5-6 levels.

Could something like this work?

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/777
• Originally reported by: tonycpsu
• Originally created at: 2011-10-01T22:35:55.188

Closes #6316, closes #10804

Per a recent request on the CPython discord, this adds entries in the table of contents for domain objects (e.g. py:function, js:module, etc).

• Example page
• Second example
• Third example

It does not support objects from the C, C++, and RST domains, as well as the option, cmdoption, and envvar objects.

A draft implementation by @agoose77 and @asmeurer was useful background, thank you both for this.

Feature or Bugfix

• Feature

Relates

• https://github.com/python/cpython/issues/83545

Ping for feedback and review, from people who have commented on the linked issues/CPython Discord thread: @Phillip-M-Feldman @slateny @pradyunsg @CAM-Gerlach @tony @agoose77 @asmeurer

A

Relates to https://github.com/sphinx-doc/sphinx/pull/10028. Sphinx plans to remove jQuery and underscore JS dependencies in version 6.0.0 (i.e., eventually, there is plenty of time). This will probably break many extensions and themes and we need to try and find at least the most important ones.

TODOs:

• [x] Remove 'internal' usage of dependencies: https://github.com/sphinx-doc/sphinx/pull/10028
• [ ] Fix dependency usage of all extensions hosted by https://github.com/sphinx-doc and https://github.com/sphinx-contrib/ in some way (either refactoring or including dependencies, but ideally refactoring).
  • [ ] https://github.com/sphinx-doc/sphinxcontrib-websupport/blob/master/sphinxcontrib/websupport/files/websupport.js
  • [ ] https://github.com/sphinx-contrib/cheeseshop/blob/master/sphinxcontrib/cheeseshop.py
  • [ ] https://github.com/sphinx-contrib/images (uses Lightbox, which relies on jQuery)
• [ ] Identify as many of the frequently used 3rd-party themes and extensions as possible and warn the maintainers.
  • [ ] https://github.com/readthedocs/sphinx_rtd_theme
  • [ ] https://github.com/ryan-roemer/sphinx-bootstrap-theme
  • [ ] https://github.com/readthedocs/sphinx-hoverxref
  • [ ] https://github.com/humitos/sphinx-version-warning
  • [ ] https://github.com/executablebooks/sphinx-thebe
  • [ ] https://github.com/useblocks/sphinx-needs
  • [ ] https://github.com/ulrobix/sphinxcontrib-contentui
  • [ ] https://github.com/schettino72/sphinx_press_theme
  • [ ] https://github.com/MrDogeBro/sphinx_rtd_dark_mode
  • [ ] https://github.com/jurasofish/sphinx-toggleprompt
  • [ ] https://github.com/BlueBrain/sphinx-bluebrain-theme
  • [ ] https://github.com/collective/sphinxcontrib-httpexample
  • [ ] https://github.com/jucacrispim/sphinx_pdj_theme
  • [ ] https://github.com/wagtail/sphinx_wagtail_theme
  • [ ] https://github.com/LinxiFan/Sphinx-theme/
  • [ ] https://github.com/typlog/sphinx-typlog-theme
  • [ ] https://github.com/useblocks/sphinx-data-viewer
  • [ ] https://github.com/ionelmc/sphinx-py3doc-enhanced-theme
• [x] Remove dependencies

Feature or Bugfix

• Feature

Purpose

This is a continuation of the work we did in #9276 and #9355. It expands some sections already started in the first part and adds some new ones, as originally proposed in #9165:

7. Describing code in Sphinx
8. Autogenerating documentation from code in Sphinx

In #9424 I started writing a section on intersphinx, but after some discussion I decided to postpone it a bit.

Also, as suggested by @tk0miya in #9424, this splits the tutorial into several documents, to make it more amenable.

Rendered version: https://sphinx--9534.org.readthedocs.build/en/9534/tutorial/index.html

cc @ericholscher

Relates

• #9165
• #9276
• #9355
• #9424

Subject: When using U+2212 to denote a negative integer, sphinx can no longer build PDF.

Problem

Unicode character U+2212 in rst files breaks PDF generation.

Procedure to reproduce the problem

$ sphinx-quickstart
[…]
$ cd in_the_directory
$ printf "\n\nHello −4 world." >> index.rst
$ make latexpdf

Error logs / results

[…]
! Package inputenc Error: Unicode char − (U+2212)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.86 Hello −
              4 world.
? 
(./minus.ind) [1] (./minus.aux) ){/usr/share/texlive/texmf-dist/fonts/enc/dvips
/base/8r.enc}</usr/share/texlive/texmf-dist/fonts/type1/urw/helvetic/uhvb8a.pfb
></usr/share/texlive/texmf-dist/fonts/type1/urw/helvetic/uhvbo8a.pfb></usr/shar
e/texlive/texmf-dist/fonts/type1/urw/times/utmb8a.pfb></usr/share/texlive/texmf
-dist/fonts/type1/urw/times/utmr8a.pfb>
Output written on minus.pdf (5 pages, 40041 bytes).
Transcript written on minus.log.
Latexmk: Index file 'minus.idx' was written
Latexmk: Log file says output to 'minus.pdf'
Latexmk: Errors, so I did not complete making targets
Collected error summary (may duplicate other messages):
  pdflatex: Command for 'pdflatex' gave return code 256
Latexmk: Use the -f option to force complete processing,
 unless error was exceeding maximum runs of latex/pdflatex.
Makefile:33: recipe for target 'minus.pdf' failed
make[1]: *** [minus.pdf] Error 12
make[1]: Leaving directory '/home/mdk/Downloads/test-minus/_build/latex'
Makefile:20: recipe for target 'latexpdf' failed
make: *** [latexpdf] Error 2

Expected results

I'd just expect my minus sign to be correctly rendered in a PDF file.

Environment info

• OS: Debian sid
• Python version: 3.6.2
• Sphinx version: 1.6.4
• texlive 2017.20171004-1

Looks like there a lots of problems with some unicode characters: https://tex.stackexchange.com/search?q=inputenc+2212

Maybe we should just add another DeclareUnicodeCharacter in utf8extra in latex.py?

clickbait! I hope this title catches some attention :)

But, really... I want to raise a concern about the developer experience of some APIs, in particular, those that are supposed to help build Sphinx extensions.

I've built a few extensions in the past and regularly hit some roadblocks along the way. Some of the walls I hit made me give up and retry in half a year or more in order to successfully fight the corresponding APIs. I must admit that part of the problems come from parts of docutils leaking into the Sphinx's public interfaces and forcing the developers to read the source of both projects to figure things out because of the poor docs.

This is how it feels right now:

Some of the problems can be hotfixed short-term by improving the docs and adding more illustrative examples. But the better long-term solution would be implementing better, ~user~developer-friendly interfaces.

Let me tell you about my latest experience. The recent (re-)discovery is sphinx.util.nodes.nested_parse_with_titles(). The doc promises a painless way to take some RST and turn in into docutils nodes that can be returned from a directive. I think I tried it about a year ago and got away just constructing some nodes manually. This time, when I needed to do something similar but more complex, I was smarter and went to read the source of the sphinx's include directive that turns out to wrap docutils' include directive and ended up seeing that it uses state_machine.insert_input() and knowing that Directive has it exposed on the object I just went ahead and used it:

self.state_machine.insert_input(
    statemachine.string2lines(rst_source),
    '[my custom included source]',
)
return []

Later, @ewjoachim figured out how to actually make sphinx.util.nodes.nested_parse_with_titles() work (https://github.com/ansible/pylibssh/pull/119/files#diff-93857a1c2f2d5628aadfb443d70a87eeR111-R121). But this is admittedly a less maintainable/readable approach that is far from being obvious even to experienced devs (https://twitter.com/Ewjoachim/status/1289323468270395393).

I'm not going to add extra examples, because I don't remember what other problems were exactly, I only have this feeling left that we can do better!

So in order for this to be not another pointless rant, let me suggest how this specific interface could be improved.

First of all, there should be function that just takes input and just returns an output. That's it! No side-effects. Passing a variable to a function only for it to be mutated by reference is an ancient technique coming from C projects. They simply didn't have much flexibility: the return value was usually some return code of a flag representing the success or the failure of an invocation. In Python, we can do better, we raise exceptions for problems and just return the results, it's that simple.

Second, creating a temporary fake node only to discard it two lines later, extracting the children messes up the readability too. It should be created if the need to use it arises, not just because some API cannot return a list...

Finally, here's an API I'm having in my mind. How about extending Directive with this method:

def convert_rst_to_nodes(self, rst_source: str) -> List[nodes.Node]:
    """Turn an RST string into a node that can be used in the document."""
    node = nodes.Element()
    node.document = self.state.document
    nested_parse_with_titles(
        state=self.state,
        content=statemachine.ViewList(
            statemachine.string2lines(rst_source),
            source='[custom RST input]',
        ),
        node=node,
    )
    return node.children

And then, it could be used as

def run(self) -> List[nodes.Node]:
    rst_source = ...
    return self.convert_rst_to_nodes(rst_source)

Hi maintainers,

According to our time based release policy, I'd propose you to release next major version in this June. What do you think about the schedule? I know there are still many issues for the release. So I might reconsider the schedule or the milestone of these issues. https://github.com/sphinx-doc/sphinx/milestone/23

Personally, I feel the master branch has grown so much since last major release. We added many features and improved codebase much (We have many refactored and deprecated our codes!). So it would be nice to go forward with postponing some issues to next major release.

In addition, I'd like to propose not to release alpha packages from our process since this release. At last two major releases, we had provided alpha packages to request for comments for users and developers on early stage of our development. But I feel that is not go well. Certainly, we'd received some issues for the release. But most of them were posted after final release. I think it would go well without alpha version because we still have beta release. The alpha release also brings prolongation of release process to us. For example, Sphinx-1.5 was released with following schedule:

• 1.5a1: 2016/9/21
• 1.5a2: 2016/10/17
• 1.5b1: 2016/11/6
• 1.5 (final): 2016/12/5 About three months were taken for 1.5 release (At 1.4, it took about 2 months). So I think alpha release is not needed for us.

Please let me know your opinion.

Describe the bug Pull request #7961 introduced MathJax v3, to be released in the next major version of Sphinx. However, there is not yet support for the new configuration format for MathJax. In particular, MathJax v3 no longer uses the nested MathJax.Hub.Config object, preferring instead to use simply MathJax.

To Reproduce

Include some mathjax_config values in conf.py and set mathjax_path to point to MathJax v3 (or use the main branch).

Following the conversion guide here: https://mathjax.github.io/MathJax-demos-web/convert-configuration/convert-configuration.html

This generated configuration using Sphinx 3 and MathJax v2:

MathJax.Hub.Config({

  "TeX": {"Macros": {"vector": ["\\vec{#1}", 1]}}, "tex2jax": {"inlineMath": [["\\(", "\\)"]], "displayMath": [["\\[", "\\]"]], "processRefs": false, "processEnvironments": false}

});

with this config parameter: MathJax.js?config=TeX-AMS-MML_HTMLorMML results in this new MathJax v3 configuration:

<script>
window.MathJax = {
  tex: {
    macros: {
      vector: ["\\vec{#1}", 1]
    },
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processRefs: false,
    processEnvironments: false,
    autoload: {
      color: [],
      colorV2: ['color']
    },
    packages: {'[+]': ['noerrors']}
  },
  options: {
    ignoreHtmlClass: 'tex2jax_ignore',
    processHtmlClass: 'tex2jax_process'
  },
  loader: {
    load: ['[tex]/noerrors']
  }
};
</script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js" id="MathJax-script"></script>

The last line there is handled by the mathjax_path, but the rest of it can't be handled by the current mathjax_config option, which assumes that MathJax.Hub.Config should be present. See also: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax_config

Expected behavior MathJax is configured properly.

Environment info

• OS: Tested on macOS, presumably any
• Python version: Tested on 3.8, presumably any
• Sphinx version: Currently, only master by default, but any version is mathjax_path is set to point to v3.
• Sphinx extensions: sphinx.ext.mathjax
• Extra tools: Tested on Firefox, presumably any browser

Additional context

• Found in the context of building a Jupyter Book: https://github.com/executablebooks/jupyter-book/issues/963

Describe the bug

I used to redefine the "light" box environments to use heavybox instead:

\renewenvironment{sphinxnote}[1] {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
\renewenvironment{sphinxhint}[1] {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
\renewenvironment{sphinximportant}[1] {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
\renewenvironment{sphinxtip}[1] {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}

However, starting with 5.1.0 I get the following error(s) when running LaTeX on the generated code:

Chapter 1.
(/usr/local/texlive/2022/texmf-dist/tex/latex/base/ts1cmss.fd)
! Missing number, treated as zero.
<to be read again>
                   \spx@note@border@top
l.181 \begin{sphinxadmonition}{note}{Note:}

with previous versions this worked fine and as intended. I haven't been able to find a workaround but I suppose this might be related to the introduction of the new configuration attributes in #10648 which doesn't exist for notes?

How to Reproduce

Add this to your conf.py and try to render a document which uses notes:

latex_elements = {
  'preamble':
      r'''\renewenvironment{sphinxnote}[1] {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
      '''
}

### Environment Information

```text
Platform:              darwin; (macOS-10.16-x86_64-i386-64bit)
Python version:        3.9.15 (main, Oct 11 2022, 22:25:13)
[Clang 12.0.0 (clang-1200.0.32.29)])
Python implementation: CPython
Sphinx version:        6.0.0
Docutils version:      0.18.1
Jinja2 version:        3.1.2

Sphinx extensions

No response

Additional context

5.0.2 works just fine, every later version I tried after that is broken.

Describe the bug

Google Chrome 108.0.5359.124:

Uncaught DOMException: Failed to execute 'querySelectorAll' on 'Document': 'div.related:first ul li:not(.right) a' is not a valid selector.
    at HTMLDocument.initialiseBizStyle (file:///Users/phprus/....../build/html/_static/bizstyle.js:21:14)
initialiseBizStyle @ bizstyle.js:21

and

Uncaught DOMException: Failed to execute 'querySelectorAll' on 'Document': 'div.related:last ul li:not(.right) a' is not a valid selector.

FireFox 108.0.1:

Uncaught DOMException: Document.querySelectorAll: 'div.related:first ul li:not(.right) a' is not a valid selector bizstyle.js:21
    initialiseBizStyle file:///Users/phprus/....../build/html/_static/bizstyle.js:21

How to Reproduce

$ echo "Content demonstrating the bug..." > index.rst
$ echo "html_theme = 'bizstyle'" > conf.py
$ sphinx-build -M html . _build
$ # open _build/html/index.html and see exception on browser console

Environment Information

Platform:              darwin; (macOS-12.6.2-arm64-arm-64bit)
Python version:        3.11.0 (main, Oct 25 2022, 13:57:33) [Clang 14.0.0 (clang-1400.0.29.202)])
Python implementation: CPython
Sphinx version:        5.3.0
Docutils version:      0.19
Jinja2 version:        3.1.2

Sphinx extensions

No response

Additional context

No response

This repo has previously been linted/upgraded using pyupgrade. Now that python <3.8 has been dropped, and the complex branch structure simplified, it might be a good time to revisit this.

My preferred approach would be to add it to CI using pre-commit.

Might need a maintainer to look at this, as they'll have a better idea which modules need to be whitelisted, etc.

i'm particularly interested in adding pyupgrade, as once in place it can be used to automatically update all the type annotations to the python 3.10+ syntax (supported in python 3.8+ using from __future__ import annotations)

Describe the bug

The Deprecated APIs documentation page still lists the removal of favico and logo variables in HTML templates as "TBD". However, they appear to have been removed for the 6.0.0 release as of PR #10562.

How to Reproduce

Build docs with a template that has a conditional inclusion of the form:

        {%- if logo -%}
        . . .
        {%- endif -%}

With 5.3.0 this would still include the content in HTML output; with 6.0.0, the content is no longer included.

Switching the conditional inclusion to {%- if logo_url -%} with 6.0.0 makes the build correctly include the content in the output again.

Environment Information

text Platform: darwin; (macOS-13.1-x86_64-i386-64bit) Python version: 3.11.1 (main, Dec 8 2022, 10:20:55) [Clang 14.0.0 (clang-1400.0.29.202)]) Python implementation: CPython Sphinx version: 6.0.0 Docutils version: 0.19 Jinja2 version: 3.1.2

Sphinx extensions

No response

Additional context

Deprecated APIs page needs an update to note that now logo and favicon have been removed in favour of logo_url and favicon_url as of 6.0.0.

I'm personally less convinced by this lint. I think there's a net benefit, but a small one. Coming from Rust, I do like the functional approach, and i like that the variable only gets bound in one place.

More a matter of taste than a clear benefit. I vote for merging, but I'm open to being convinced otherwise