sphinx/tests/test_environment/test_environment_toctree.py

"""Test the sphinx.environment.adapters.toctree."""

import pytest
from docutils import nodes
from docutils.nodes import bullet_list, list_item, literal, reference, title

from sphinx import addnodes
from sphinx.addnodes import compact_paragraph, only
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.environment.adapters.toctree import document_toc, global_toctree_for_doc
from sphinx.testing.util import assert_node


@pytest.mark.sphinx('xml', testroot='toctree')
@pytest.mark.test_params(shared_result='test_environment_toctree_basic')
def test_process_doc(app):
    app.build()
    # tocs
    toctree = app.env.tocs['index']
    assert_node(toctree,
                [bullet_list, ([list_item, (compact_paragraph,  # [0][0]
                                            [bullet_list, (addnodes.toctree,  # [0][1][0]
                                                           only,  # [0][1][1]
                                                           list_item)])],  # [0][1][2]
                               [list_item, (compact_paragraph,  # [1][0]
                                            [bullet_list, (addnodes.toctree,  # [1][1][0]
                                                           addnodes.toctree)])],  # [1][1][1]
                               list_item)])

    assert_node(toctree[0][0],
                [compact_paragraph, reference, "Welcome to Sphinx Tests’s documentation!"])
    assert_node(toctree[0][0][0], reference, anchorname='')
    assert_node(toctree[0][1][0], addnodes.toctree,
                caption="Table of Contents", glob=False, hidden=False,
                titlesonly=False, maxdepth=2, numbered=999,
                entries=[(None, 'foo'), (None, 'bar'), (None, 'https://sphinx-doc.org/'),
                         (None, 'self')],
                includefiles=['foo', 'bar'])

    # only branch
    assert_node(toctree[0][1][1], addnodes.only, expr="html")
    assert_node(toctree[0][1][1],
                [only, list_item, ([compact_paragraph, reference, "Section for HTML"],
                                   [bullet_list, addnodes.toctree])])
    assert_node(toctree[0][1][1][0][0][0], reference, anchorname='#section-for-html')
    assert_node(toctree[0][1][1][0][1][0], addnodes.toctree,
                caption=None, glob=False, hidden=False, entries=[(None, 'baz')],
                includefiles=['baz'], titlesonly=False, maxdepth=-1, numbered=0)
    assert_node(toctree[0][1][2],
                ([compact_paragraph, reference, "subsection"],
                 [bullet_list, list_item, compact_paragraph, reference, "subsubsection"]))

    assert_node(toctree[1][0],
                [compact_paragraph, reference, "Test for issue #1157"])
    assert_node(toctree[1][0][0], reference, anchorname='#test-for-issue-1157')
    assert_node(toctree[1][1][0], addnodes.toctree,
                caption=None, entries=[], glob=False, hidden=False,
                titlesonly=False, maxdepth=-1, numbered=0)
    assert_node(toctree[1][1][1], addnodes.toctree,
                caption=None, glob=False, hidden=True,
                titlesonly=False, maxdepth=-1, numbered=0,
                entries=[('Latest reference', 'https://sphinx-doc.org/latest/'),
                         ('Python', 'https://python.org/')])

    assert_node(toctree[2][0],
                [compact_paragraph, reference, "Indices and tables"])

    # other collections
    assert app.env.toc_num_entries['index'] == 6
    assert app.env.toctree_includes['index'] == ['foo', 'bar', 'baz']
    assert app.env.files_to_rebuild['foo'] == {'index'}
    assert app.env.files_to_rebuild['bar'] == {'index'}
    assert app.env.files_to_rebuild['baz'] == {'index'}
    assert app.env.glob_toctrees == set()
    assert app.env.numbered_toctrees == {'index'}

    # qux has no section title
    assert len(app.env.tocs['qux']) == 0
    assert_node(app.env.tocs['qux'], nodes.bullet_list)
    assert app.env.toc_num_entries['qux'] == 0
    assert 'qux' not in app.env.toctree_includes


@pytest.mark.sphinx('dummy', testroot='toctree-glob')
def test_glob(app):
    includefiles = ['foo', 'bar/index', 'bar/bar_1', 'bar/bar_2',
                    'bar/bar_3', 'baz', 'qux/index']

    app.build()

    # tocs
    toctree = app.env.tocs['index']
    assert_node(toctree,
                [bullet_list, list_item, (compact_paragraph,  # [0][0]
                                          [bullet_list, (list_item,  # [0][1][0]
                                                         list_item)])])  # [0][1][1]

    assert_node(toctree[0][0],
                [compact_paragraph, reference, "test-toctree-glob"])
    assert_node(toctree[0][1][0],
                [list_item, ([compact_paragraph, reference, "normal order"],
                             [bullet_list, addnodes.toctree])])  # [0][1][0][1][0]
    assert_node(toctree[0][1][0][1][0], addnodes.toctree, caption=None,
                glob=True, hidden=False, titlesonly=False,
                maxdepth=-1, numbered=0, includefiles=includefiles,
                entries=[(None, 'foo'), (None, 'bar/index'), (None, 'bar/bar_1'),
                         (None, 'bar/bar_2'), (None, 'bar/bar_3'), (None, 'baz'),
                         (None, 'qux/index'),
                         ('hyperref', 'https://sphinx-doc.org/?q=sphinx')])
    assert_node(toctree[0][1][1],
                [list_item, ([compact_paragraph, reference, "reversed order"],
                             [bullet_list, addnodes.toctree])])  # [0][1][1][1][0]
    assert_node(toctree[0][1][1][1][0], addnodes.toctree, caption=None,
                glob=True, hidden=False, titlesonly=False,
                maxdepth=-1, numbered=0, includefiles=list(reversed(includefiles)),
                entries=[(None, 'qux/index'), (None, 'baz'), (None, 'bar/bar_3'),
                         (None, 'bar/bar_2'), (None, 'bar/bar_1'), (None, 'bar/index'),
                         (None, 'foo')])

    # other collections
    assert app.env.toc_num_entries['index'] == 3
    assert app.env.toctree_includes['index'] == includefiles + list(reversed(includefiles))
    for file in includefiles:
        assert 'index' in app.env.files_to_rebuild[file]
    assert 'index' in app.env.glob_toctrees
    assert app.env.numbered_toctrees == set()


@pytest.mark.sphinx('dummy', testroot='toctree-domain-objects')
def test_domain_objects(app):
    app.build()

    assert app.env.toc_num_entries['index'] == 0
    assert app.env.toc_num_entries['domains'] == 9
    assert app.env.toctree_includes['index'] == ['domains', 'document_scoping']
    assert 'index' in app.env.files_to_rebuild['domains']
    assert app.env.glob_toctrees == set()
    assert app.env.numbered_toctrees == {'index'}

    # tocs
    toctree = app.env.tocs['domains']
    assert_node(toctree,
                [bullet_list, list_item, (compact_paragraph,  # [0][0]
                                          [bullet_list, (list_item,  # [0][1][0]
                                                         [list_item,  # [0][1][1]
                                                          (compact_paragraph,  # [0][1][1][0]
                                                           [bullet_list, (list_item,  # [0][1][1][1][0]
                                                                          list_item,
                                                                          list_item,
                                                                          list_item)])],  # [0][1][1][1][3]
                                                         list_item,
                                                         list_item)])])  # [0][1][1]

    assert_node(toctree[0][0],
                [compact_paragraph, reference, "test-domain-objects"])

    assert_node(toctree[0][1][0],
                [list_item, ([compact_paragraph, reference, literal, "world()"])])

    assert_node(toctree[0][1][1][1][3],
                [list_item, ([compact_paragraph, reference, literal, "HelloWorldPrinter.print()"])])


@pytest.mark.sphinx('dummy', testroot='toctree-domain-objects')
def test_domain_objects_document_scoping(app):
    app.build()

    # tocs
    toctree = app.env.tocs['document_scoping']
    assert_node(
        toctree,
        [bullet_list, list_item, (
            compact_paragraph,  # [0][0]
            [bullet_list, (  # [0][1]
                [list_item, compact_paragraph, reference, literal, 'ClassLevel1a'],  # [0][1][0]
                [list_item, (  # [0][1][1]
                    [compact_paragraph, reference, literal, 'ClassLevel1b'],  # [0][1][1][0]
                    [bullet_list, list_item, compact_paragraph, reference, literal, 'ClassLevel1b.f()'],  # [0][1][1][1][0]
                )],
                [list_item, compact_paragraph, reference, literal, 'ClassLevel1a.g()'],  # [0][1][2]
                [list_item, compact_paragraph, reference, literal, 'ClassLevel1b.g()'],  # [0][1][3]
                [list_item, (  # [0][1][4]
                    [compact_paragraph, reference, 'Level 2'],  # [0][1][4][0]
                    [bullet_list, (  # [0][1][4][1]
                        [list_item, compact_paragraph, reference, literal, 'ClassLevel2a'],  # [0][1][4][1][0]
                        [list_item, (  # [0][1][4][1][1]
                            [compact_paragraph, reference, literal, 'ClassLevel2b'],  # [0][1][4][1][1][0]
                            [bullet_list, list_item, compact_paragraph, reference, literal, 'ClassLevel2b.f()'],  # [0][1][4][1][1][1][0]
                        )],
                        [list_item, compact_paragraph, reference, literal, 'ClassLevel2a.g()'],  # [0][1][4][1][2]
                        [list_item, compact_paragraph, reference, literal, 'ClassLevel2b.g()'],  # [0][1][4][1][3]
                    )],
                )],
            )],
        )],
    )


@pytest.mark.sphinx('xml', testroot='toctree')
@pytest.mark.test_params(shared_result='test_environment_toctree_basic')
def test_document_toc(app):
    app.build()
    toctree = document_toc(app.env, 'index', app.builder.tags)

    assert_node(toctree,
                [bullet_list, ([list_item, (compact_paragraph,  # [0][0]
                                            [bullet_list, (addnodes.toctree,  # [0][1][0]
                                                           list_item)])],  # [0][1][1]
                               [list_item, (compact_paragraph,  # [1][0]
                                            [bullet_list, (addnodes.toctree,
                                                           addnodes.toctree)])],
                               [list_item, compact_paragraph])])  # [2][0]
    assert_node(toctree[0][0],
                [compact_paragraph, reference, "Welcome to Sphinx Tests’s documentation!"])
    assert_node(toctree[0][1][1],
                ([compact_paragraph, reference, "subsection"],
                 [bullet_list, list_item, compact_paragraph, reference, "subsubsection"]))
    assert_node(toctree[1][0],
                [compact_paragraph, reference, "Test for issue #1157"])
    assert_node(toctree[2][0],
                [compact_paragraph, reference, "Indices and tables"])


@pytest.mark.sphinx('xml', testroot='toctree')
@pytest.mark.test_params(shared_result='test_environment_toctree_basic')
def test_document_toc_only(app):
    app.build()
    builder = StandaloneHTMLBuilder(app, app.env)
    toctree = document_toc(app.env, 'index', builder.tags)

    assert_node(toctree,
                [bullet_list, ([list_item, (compact_paragraph,  # [0][0]
                                            [bullet_list, (addnodes.toctree,  # [0][1][0]
                                                           list_item,  # [0][1][1]
                                                           list_item)])],  # [0][1][2]
                               [list_item, (compact_paragraph,  # [1][0]
                                            [bullet_list, (addnodes.toctree,
                                                           addnodes.toctree)])],
                               [list_item, compact_paragraph])])  # [2][0]
    assert_node(toctree[0][0],
                [compact_paragraph, reference, "Welcome to Sphinx Tests’s documentation!"])
    assert_node(toctree[0][1][1],
                ([compact_paragraph, reference, "Section for HTML"],
                 [bullet_list, addnodes.toctree]))
    assert_node(toctree[0][1][2],
                ([compact_paragraph, reference, "subsection"],
                 [bullet_list, list_item, compact_paragraph, reference, "subsubsection"]))
    assert_node(toctree[1][0],
                [compact_paragraph, reference, "Test for issue #1157"])
    assert_node(toctree[2][0],
                [compact_paragraph, reference, "Indices and tables"])


@pytest.mark.sphinx('xml', testroot='toctree')
@pytest.mark.test_params(shared_result='test_environment_toctree_basic')
def test_document_toc_tocdepth(app):
    app.build()
    toctree = document_toc(app.env, 'tocdepth', app.builder.tags)

    assert_node(toctree,
                [bullet_list, list_item, (compact_paragraph,  # [0][0]
                                          bullet_list)])  # [0][1]
    assert_node(toctree[0][0],
                [compact_paragraph, reference, "level 1"])
    assert_node(toctree[0][1],
                [bullet_list, list_item, compact_paragraph, reference, "level 2"])


@pytest.mark.sphinx('xml', testroot='toctree')
@pytest.mark.test_params(shared_result='test_environment_toctree_basic')
def test_global_toctree_for_doc(app):
    app.build()
    toctree = global_toctree_for_doc(app.env, 'index', app.builder, collapse=False)
    assert_node(toctree,
                [compact_paragraph, ([title, "Table of Contents"],
                                     bullet_list,
                                     bullet_list,
                                     bullet_list)])

    assert_node(toctree[1],
                ([list_item, ([compact_paragraph, reference, "foo"],
                              bullet_list)],
                 [list_item, compact_paragraph, reference, "bar"],
                 [list_item, compact_paragraph, reference, "https://sphinx-doc.org/"],
                 [list_item, compact_paragraph, reference,
                  "Welcome to Sphinx Tests’s documentation!"]))
    assert_node(toctree[1][0][1],
                ([list_item, compact_paragraph, reference, "quux"],
                 [list_item, compact_paragraph, reference, "foo.1"],
                 [list_item, compact_paragraph, reference, "foo.2"]))

    assert_node(toctree[1][0][0][0], reference, refuri="foo", secnumber=[1])
    assert_node(toctree[1][0][1][0][0][0], reference, refuri="quux", secnumber=[1, 1])
    assert_node(toctree[1][0][1][1][0][0], reference, refuri="foo#foo-1", secnumber=[1, 2])
    assert_node(toctree[1][0][1][2][0][0], reference, refuri="foo#foo-2", secnumber=[1, 3])
    assert_node(toctree[1][1][0][0], reference, refuri="bar", secnumber=[2])
    assert_node(toctree[1][2][0][0], reference, refuri="https://sphinx-doc.org/")
    assert_node(toctree[1][3][0][0], reference, refuri="")

    assert_node(toctree[2],
                [bullet_list, list_item, compact_paragraph, reference, "baz"])
    assert_node(toctree[3],
                ([list_item, compact_paragraph, reference, "Latest reference"],
                 [list_item, compact_paragraph, reference, "Python"]))
    assert_node(toctree[3][0][0][0], reference, refuri="https://sphinx-doc.org/latest/")
    assert_node(toctree[3][1][0][0], reference, refuri="https://python.org/")


@pytest.mark.sphinx('xml', testroot='toctree')
@pytest.mark.test_params(shared_result='test_environment_toctree_basic')
def test_global_toctree_for_doc_collapse(app):
    app.build()
    toctree = global_toctree_for_doc(app.env, 'index', app.builder, collapse=True)
    assert_node(toctree,
                [compact_paragraph, ([title, "Table of Contents"],
                                     bullet_list,
                                     bullet_list,
                                     bullet_list)])

    assert_node(toctree[1],
                ([list_item, compact_paragraph, reference, "foo"],
                 [list_item, compact_paragraph, reference, "bar"],
                 [list_item, compact_paragraph, reference, "https://sphinx-doc.org/"],
                 [list_item, compact_paragraph, reference,
                  "Welcome to Sphinx Tests’s documentation!"]))
    assert_node(toctree[1][0][0][0], reference, refuri="foo", secnumber=[1])
    assert_node(toctree[1][1][0][0], reference, refuri="bar", secnumber=[2])
    assert_node(toctree[1][2][0][0], reference, refuri="https://sphinx-doc.org/")
    assert_node(toctree[1][3][0][0], reference, refuri="")

    assert_node(toctree[2],
                [bullet_list, list_item, compact_paragraph, reference, "baz"])
    assert_node(toctree[3],
                ([list_item, compact_paragraph, reference, "Latest reference"],
                 [list_item, compact_paragraph, reference, "Python"]))
    assert_node(toctree[3][0][0][0], reference, refuri="https://sphinx-doc.org/latest/")
    assert_node(toctree[3][1][0][0], reference, refuri="https://python.org/")


@pytest.mark.sphinx('xml', testroot='toctree')
@pytest.mark.test_params(shared_result='test_environment_toctree_basic')
def test_global_toctree_for_doc_maxdepth(app):
    app.build()
    toctree = global_toctree_for_doc(app.env, 'index', app.builder,
                                     collapse=False, maxdepth=3)
    assert_node(toctree,
                [compact_paragraph, ([title, "Table of Contents"],
                                     bullet_list,
                                     bullet_list,
                                     bullet_list)])

    assert_node(toctree[1],
                ([list_item, ([compact_paragraph, reference, "foo"],
                              bullet_list)],
                 [list_item, compact_paragraph, reference, "bar"],
                 [list_item, compact_paragraph, reference, "https://sphinx-doc.org/"],
                 [list_item, compact_paragraph, reference,
                  "Welcome to Sphinx Tests’s documentation!"]))
    assert_node(toctree[1][0][1],
                ([list_item, compact_paragraph, reference, "quux"],
                 [list_item, ([compact_paragraph, reference, "foo.1"],
                              bullet_list)],
                 [list_item, compact_paragraph, reference, "foo.2"]))
    assert_node(toctree[1][0][1][1][1],
                [bullet_list, list_item, compact_paragraph, reference, "foo.1-1"])

    assert_node(toctree[1][0][0][0], reference, refuri="foo", secnumber=[1])
    assert_node(toctree[1][0][1][0][0][0], reference, refuri="quux", secnumber=[1, 1])
    assert_node(toctree[1][0][1][1][0][0], reference, refuri="foo#foo-1", secnumber=[1, 2])
    assert_node(toctree[1][0][1][1][1][0][0][0],
                reference, refuri="foo#foo-1-1", secnumber=[1, 2, 1])
    assert_node(toctree[1][0][1][2][0][0], reference, refuri="foo#foo-2", secnumber=[1, 3])
    assert_node(toctree[1][1][0][0], reference, refuri="bar", secnumber=[2])
    assert_node(toctree[1][2][0][0], reference, refuri="https://sphinx-doc.org/")
    assert_node(toctree[1][3][0][0], reference, refuri="")

    assert_node(toctree[2],
                [bullet_list, list_item, compact_paragraph, reference, "baz"])
    assert_node(toctree[3],
                ([list_item, compact_paragraph, reference, "Latest reference"],
                 [list_item, compact_paragraph, reference, "Python"]))
    assert_node(toctree[3][0][0][0], reference, refuri="https://sphinx-doc.org/latest/")
    assert_node(toctree[3][1][0][0], reference, refuri="https://python.org/")


@pytest.mark.sphinx('xml', testroot='toctree')
@pytest.mark.test_params(shared_result='test_environment_toctree_basic')
def test_global_toctree_for_doc_includehidden(app):
    app.build()
    toctree = global_toctree_for_doc(app.env, 'index', app.builder,
                                     collapse=False, includehidden=False)
    assert_node(toctree,
                [compact_paragraph, ([title, "Table of Contents"],
                                     bullet_list,
                                     bullet_list)])

    assert_node(toctree[1],
                ([list_item, ([compact_paragraph, reference, "foo"],
                              bullet_list)],
                 [list_item, compact_paragraph, reference, "bar"],
                 [list_item, compact_paragraph, reference, "https://sphinx-doc.org/"],
                 [list_item, compact_paragraph, reference,
                  "Welcome to Sphinx Tests’s documentation!"]))
    assert_node(toctree[1][0][1],
                ([list_item, compact_paragraph, reference, "quux"],
                 [list_item, compact_paragraph, reference, "foo.1"],
                 [list_item, compact_paragraph, reference, "foo.2"]))

    assert_node(toctree[1][0][0][0], reference, refuri="foo", secnumber=[1])
    assert_node(toctree[1][0][1][0][0][0], reference, refuri="quux", secnumber=[1, 1])
    assert_node(toctree[1][0][1][1][0][0], reference, refuri="foo#foo-1", secnumber=[1, 2])
    assert_node(toctree[1][0][1][2][0][0], reference, refuri="foo#foo-2", secnumber=[1, 3])
    assert_node(toctree[1][1][0][0], reference, refuri="bar", secnumber=[2])
    assert_node(toctree[1][2][0][0], reference, refuri="https://sphinx-doc.org/")

    assert_node(toctree[2],
                [bullet_list, list_item, compact_paragraph, reference, "baz"])


@pytest.mark.sphinx('xml', testroot='toctree-index')
def test_toctree_index(app):
    app.build()
    toctree = app.env.tocs['index']
    assert_node(toctree,
                [bullet_list, ([list_item, (compact_paragraph,  # [0][0]
                                            [bullet_list, (addnodes.toctree,  # [0][1][0]
                                                           addnodes.toctree)])])])  # [0][1][1]
    assert_node(toctree[0][1][1], addnodes.toctree,
                caption="Indices", glob=False, hidden=False,
                titlesonly=False, maxdepth=-1, numbered=0,
                entries=[(None, 'genindex'), (None, 'modindex'), (None, 'search')])