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

Sphinx LaTeX renders aligned figure using wrapfig package which is notoriously problematic but is the only available one in LaTeX world to try to achieve flowing of text around figure. Unfortunately it can work only with manual fine-tuning, and in examining our root test I encountered such an instance of problem:

• the figure itself completely disappears
• and then all lists (of various types) spill over in left margin, even if separated by text and sections from figure location...

Here is an example output:

How to Reproduce

Use this index.rst (the text says that figure has both align and width, but I remove width at some point which has no impact on the problem)

====
TEST
====

WEIRD PROBLEM
=============

Figures
-------

.. figure:: simg.png
   :align: right

   caption of figure with align and width option

   legend

   still in legend

Misc stuff
----------


text

term1:
  desc1

term2:
  desc2

text

and for the image simg.png I used

Nota Bene: if one removes the WEIRD PROBLEM heading, so that the sections become LaTeX chapters, then the problem disappears. It shows only in the circumstances above of LaTeX using \section.

Environment Information

Python version:        3.10.9 (v3.10.9:1dd9be6584, Dec  6 2022, 14:37:36) [Clang 13.0.0 (clang-1300.0.29.30)])
Python implementation: CPython
Sphinx version:        6.0.1+/29e12ec4d
Docutils version:      0.19
Jinja2 version:        3.1.2
Pygments version:      2.14.0

Sphinx extensions

none

Additional context

Adding usage of the width option to the figure directive does not change the outcome.

I downgraded to TeXLive 2019 from TeXLive 2022 to make sure this is not cause by some too recent LaTeX.

The LaTeX code produced by Sphinx looks like this

\begin{wrapfigure}{r}{0pt}
\centering
\noindent\sphinxincludegraphics{{simg}.png}
\caption{caption of figure with align and width option}\label{\detokenize{index:id1}}
\begin{sphinxlegend}
\sphinxAtStartPar
legend

\sphinxAtStartPar
still in legend
\end{sphinxlegend}
\end{wrapfigure}


\section{Misc stuff}

If I add \mbox{} after the wrapfigure environment in the LaTeX file the problem disappears:

Doing this generally will cause extra vertical space in existing documents where the problem does not show because the figure is followed by a text paragraph.

However it may help in the well-known issue that wrapfigure should not be followed by some list environment.

Update: another screenshot showing things working somewhat ok

In real life, people who use wrapfigure in LaTeX adjust manually using some extra parameter so that wrapping fits better the included figure and legend. It is impossible to do this automatically in satisfying manner, to the best of my knowledge.

Describe the bug

When including a graphviz graph that itself has a reference to a file by relative path (embedded image or hyperlink), the link target is wrong in the rendered docs when using svg format.

This is because the rendered graphviz file is put in the _images folder in the built documentation, irrespective of where the original documentation file was, hence any relative path (e.g.../../_stativ/image.svg) is now invalid since the root of the graph changed.

I have a PR that would fix this by rewriting relative URLs in generated SVGs

How to Reproduce

index.rst:

graphviz
========

.. graphviz::
   :align: center

   digraph test {
     foo [label="foo", URL="#graphviz", target="_parent"]
     bar [label="bar", image="./_static/images/test.svg"]
     baz [label="baz", URL="./_static/images/test.svg"]
     foo -> bar -> baz
   }

conf.py:

extensions = ['sphinx.ext.graphviz']
exclude_patterns = ['_build']
html_static_path = ["_static"]

The rendered svg still points to e.g. ./_static/images/test.svg, even though since it's now in _images/, it should be ../_static/images/test.svg

Environment Information

Platform:              linux; (Linux-6.1.1-arch1-1-x86_64-with-glibc2.36)
Python version:        3.9.15 (main, Nov 18 2022, 14:40:14)
[GCC 12.2.0])
Python implementation: CPython
Sphinx version:        6.0.0
Docutils version:      0.19
Jinja2 version:        3.0.3

Sphinx extensions

`['sphinx.ext.graphviz']`

Additional context

No response

Describe the bug

Whenever a "SphinxError" is raised, the next build is always a full build without using the pickles. This causes usability issues in large projects whenever an error is created in a file and fixed.

The expectation is that only the changed file (where the error is fixed) is rebuilt.

How to Reproduce

1. Do a sphinx-build
2. Do a second sphinx-build without making any changes (to make sure that incremental build works)
3. Introduce any error in a file which raises a SphinxError (not a SphinxWarning)
4. Do a sphinx-build

All source files are marked as changed and read in again.

Environment Information

Sphinx: 5.3.0

Sphinx extensions

No response

Additional context

No response

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)