Python sphinx.version_info() Examples

def run(self):
        command = [
            None,  # in Sphinx < 1.7.0 the first command-line argument was parsed, in 1.7.0 it became argv[1:]
            '--force',  # overwrite existing files
            '--module-first',  # put module documentation before submodule documentation
            '--separate',  # put documentation for each module on its own page
            '-o', './docs/_autosummary',  # where to save the output files
            'msl',  # the path to the Python package to document
        ]

        import sphinx
        if sphinx.version_info[:2] < (1, 7):
            from sphinx.apidoc import main
        else:
            from sphinx.ext.apidoc import main  # Sphinx also changed the location of apidoc.main
            command.pop(0)

        main(command)
        sys.exit(0) 

def run(self):
        import sphinx

        command = [
            None,  # in Sphinx < 1.7.0 the first command-line argument was parsed, in 1.7.0 it became argv[1:]
            '-b', 'html',  # the builder to use, e.g., create a HTML version of the documentation
            '-a',  # generate output for all files
            '-E',  # ignore cached files, forces to re-read all source files from disk
            'docs',  # the source directory where the documentation files are located
            './docs/_build/html',  # where to save the output files
        ]

        if sphinx.version_info[:2] < (1, 7):
            from sphinx import build_main
        else:
            from sphinx.cmd.build import build_main  # Sphinx also changed the location of build_main
            command.pop(0)

        build_main(command)
        sys.exit(0) 

def test_doc_build_html(app, status, warning):

    # Somehow the xml-tree in extract_needs_from_html() works not correctly with py37 and specific
    # extracts, which are needed for sphinx >3.0 only.
    # Everything with Py3.8 is fine again and also Py3.7 with sphinx<3 works here.
    if sys.version_info[0] == 3 and sys.version_info[1] == 7 and sphinx.version_info[0] >= 3:
        return True

    app.build()
    html = (app.outdir / 'index.html').read_text()
    assert 'title_clean_layout' in html
    assert 'title_complete_layout' in html
    assert 'title_focus_layout' not in html
    assert 'title_example_layout' in html

    needs = extract_needs_from_html(html)
    assert len(needs) == 4

    assert '<tr class="footer row-even"><td class="footer_left" colspan="2">' in html 

def sphinx_build(src_dir, build_dir):
    import sphinx
    cmd = [ '-b', 'html',
            '-d', op.join(build_dir, 'doctrees'),
            src_dir,  # Source
            op.join(build_dir, 'html'),  # Dest
            ]
    
    if sphinx.version_info > (1, 7):
        import sphinx.cmd.build
        ret = sphinx.cmd.build.build_main(cmd)
    else:
        ret = sphinx.build_main(['sphinx-build'] + cmd)
    if ret != 0:
        raise RuntimeError('Sphinx error: %s' % ret)
    print("Build finished. The HTML pages are in %s/html." % build_dir) 

def sphinx_build(src_dir, build_dir):
    import sphinx
    cmd = [ '-b', 'html',
            '-d', op.join(build_dir, 'doctrees'),
            src_dir,  # Source
            op.join(build_dir, 'html'),  # Dest
            ]

    if sphinx.version_info > (1, 7):
        import sphinx.cmd.build
        ret = sphinx.cmd.build.build_main(cmd)
    else:
        ret = sphinx.build_main(['sphinx-build'] + cmd)
    if ret != 0:
        raise RuntimeError('Sphinx error: %s' % ret)
    print("Build finished. The HTML pages are in %s/html." % build_dir) 

def setup(app):
    app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))

    if sphinx.version_info >= (1, 8, 0):
        # Add Sphinx message catalog for newer versions of Sphinx
        # See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
        rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
        app.add_message_catalog('sphinx', rtd_locale_path) 

def test_empty():
    """Local TOC is showing, as toctree was empty"""
    for (app, status, warning) in build_all('test-empty'):
        assert app.env.get_doctree('index').traverse(addnodes.toctree)
        content = open(os.path.join(app.outdir, 'index.html')).read()
        if sphinx.version_info < (1, 4):
            if isinstance(app.builder, SingleFileHTMLBuilder):
                assert '<div class="toctree-wrapper compound">\n</div>' in content
                assert '<div class="local-toc">' in content
            else:
                global_toc = (
                    '<div class="toctree-wrapper compound">\n'
                    '<ul class="simple">\n</ul>\n'
                    '</div>'
                )
                local_toc = (
                    '<div class="local-toc"><ul class="simple">'
                    '</ul>\n</div>'
                )
                assert global_toc in content
                assert local_toc not in content
        else:
            global_toc = '<div class="toctree-wrapper compound">\n</div>'
            local_toc = (
                '<div class="local-toc"><ul>\n'
                '<li><a class="reference internal" href="#">test-empty</a></li>'
                '</ul>\n</div>'
            )
            assert global_toc in content
            assert local_toc not in content 

def setup(app):
    setup.app = app

    # Add visit/depart methods to HTML-Translator:
    def visit_latex_math_html(self, node):
        source = self.document.attributes['source']
        self.body.append(latex2html(node, source))

    def depart_latex_math_html(self, node):
        pass

    # Add visit/depart methods to LaTeX-Translator:
    def visit_latex_math_latex(self, node):
        inline = isinstance(node.parent, nodes.TextElement)
        if inline:
            self.body.append('$%s$' % node['latex'])
        else:
            self.body.extend(['\\begin{equation}',
                              node['latex'],
                              '\\end{equation}'])

    def depart_latex_math_latex(self, node):
        pass

    app.add_node(latex_math,
                 html=(visit_latex_math_html, depart_latex_math_html),
                 latex=(visit_latex_math_latex, depart_latex_math_latex))
    app.add_role('mathmpl', math_role)
    app.add_directive('mathmpl', MathDirective)
    if sphinx.version_info < (1, 8):
        app.add_role('math', math_role)
        app.add_directive('math', MathDirective)

    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
    return metadata 

def setup(app):
    setup.app = app

    # Add visit/depart methods to HTML-Translator:
    def visit_latex_math_html(self, node):
        source = self.document.attributes['source']
        self.body.append(latex2html(node, source))

    def depart_latex_math_html(self, node):
        pass

    # Add visit/depart methods to LaTeX-Translator:
    def visit_latex_math_latex(self, node):
        inline = isinstance(node.parent, nodes.TextElement)
        if inline:
            self.body.append('$%s$' % node['latex'])
        else:
            self.body.extend(['\\begin{equation}',
                              node['latex'],
                              '\\end{equation}'])

    def depart_latex_math_latex(self, node):
        pass

    app.add_node(latex_math,
                 html=(visit_latex_math_html, depart_latex_math_html),
                 latex=(visit_latex_math_latex, depart_latex_math_latex))
    app.add_role('mathmpl', math_role)
    app.add_directive('mathmpl', math_directive,
                      True, (0, 0, 0), **options_spec)
    if sphinx.version_info < (1, 8):
        app.add_role('math', math_role)
        app.add_directive('math', math_directive,
                          True, (0, 0, 0), **options_spec)

    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
    return metadata 

def test_advanced(app, status, warning):
    if sphinx.version_info < (1, 8, 0):
        pytest.xfail('This should fail on older Sphinx versions')

    logging.setup(app, status, warning)
    app.builder.build_all()

    assert (app.srcdir / 'api').isdir()
    assert (app.srcdir / 'api' / 'custom.rst').exists()
    for module in [
            'apidoc_dummy_module.rst',
            'apidoc_dummy_package.apidoc_dummy_submodule_a.rst',
            'apidoc_dummy_package.apidoc_dummy_submodule_b.rst',
            'apidoc_dummy_package._apidoc_private_dummy_submodule.rst',
    ]:
        assert (app.srcdir / 'api' / module).exists()
    assert (app.srcdir / 'api' / 'apidoc_dummy_package.rst').exists()
    assert not (app.srcdir / 'api' / 'conf.rst').exists()

    with open(app.srcdir / 'api' / 'apidoc_dummy_package.rst') as fh:
        package_doc = [x.strip() for x in fh.readlines()]

    # The 'Module contents' header isn't present if '--module-first' used
    assert 'Module contents' not in package_doc

    assert (app.outdir / 'api').isdir()
    assert (app.outdir / 'api' / 'custom.html').exists()
    for module in [
            'apidoc_dummy_module.html',
            'apidoc_dummy_package.apidoc_dummy_submodule_a.html',
            'apidoc_dummy_package.apidoc_dummy_submodule_b.html',
            'apidoc_dummy_package._apidoc_private_dummy_submodule.html',
    ]:
        assert (app.outdir / 'api' / module).exists()
    assert (app.outdir / 'api' / 'apidoc_dummy_package.html').exists()
    assert not (app.outdir / 'api' / 'conf.html').exists()

    assert not warning.getvalue() 

def setup(app):
    """Initialize Sphinx extension."""
    import sphinx
    from .parser import CommonMarkParser

    if sphinx.version_info >= (1, 8):
        app.add_source_suffix('.md', 'markdown')
        app.add_source_parser(CommonMarkParser)
    elif sphinx.version_info >= (1, 4):
        app.add_source_parser('.md', CommonMarkParser)

    return {'version': __version__, 'parallel_read_safe': True} 

def test_doc_needtable_options(app, status, warning):
    import sphinx
    app.build()
    html = Path(app.outdir, 'test_options.html').read_text()
    assert 'SP_TOO_003' in html
    assert 'id="needtable-test_options-0"' in html
    assert 'id="needtable-test_options-1"' in html

    if sphinx.version_info[0] < 2:
        column_order = """
<tr class="row-odd"><th class="head">Incoming</th>
<th class="head">ID</th>
<th class="head">Tags</th>
<th class="head">Status</th>
<th class="head">Title</th>
"""
    else:
        column_order = """
<tr class="row-odd"><th class="head"><p>Incoming</p></th>
<th class="head"><p>ID</p></th>
<th class="head"><p>Tags</p></th>
<th class="head"><p>Status</p></th>
<th class="head"><p>Title</p></th>
</tr>
"""

    assert column_order in html 

def setup(app):
    setup.app = app

    # Add visit/depart methods to HTML-Translator:
    def visit_latex_math_html(self, node):
        source = self.document.attributes['source']
        self.body.append(latex2html(node, source))

    def depart_latex_math_html(self, node):
        pass

    # Add visit/depart methods to LaTeX-Translator:
    def visit_latex_math_latex(self, node):
        inline = isinstance(node.parent, nodes.TextElement)
        if inline:
            self.body.append('$%s$' % node['latex'])
        else:
            self.body.extend(['\\begin{equation}',
                              node['latex'],
                              '\\end{equation}'])

    def depart_latex_math_latex(self, node):
        pass

    app.add_node(latex_math,
                 html=(visit_latex_math_html, depart_latex_math_html),
                 latex=(visit_latex_math_latex, depart_latex_math_latex))
    app.add_role('mathmpl', math_role)
    app.add_directive('mathmpl', math_directive,
                      True, (0, 0, 0), **options_spec)
    if sphinx.version_info < (1, 8):
        app.add_role('math', math_role)
        app.add_directive('math', math_directive,
                          True, (0, 0, 0), **options_spec)

    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
    return metadata 

def setup(app):
    setup.app = app

    # Add visit/depart methods to HTML-Translator:
    def visit_latex_math_html(self, node):
        source = self.document.attributes['source']
        self.body.append(latex2html(node, source))

    def depart_latex_math_html(self, node):
        pass

    # Add visit/depart methods to LaTeX-Translator:
    def visit_latex_math_latex(self, node):
        inline = isinstance(node.parent, nodes.TextElement)
        if inline:
            self.body.append('$%s$' % node['latex'])
        else:
            self.body.extend(['\\begin{equation}',
                              node['latex'],
                              '\\end{equation}'])

    def depart_latex_math_latex(self, node):
        pass

    app.add_node(latex_math,
                 html=(visit_latex_math_html, depart_latex_math_html),
                 latex=(visit_latex_math_latex, depart_latex_math_latex))
    app.add_role('mathmpl', math_role)
    app.add_directive('mathmpl', math_directive,
                      True, (0, 0, 0), **options_spec)
    if sphinx.version_info < (1, 8):
        app.add_role('math', math_role)
        app.add_directive('math', math_directive,
                          True, (0, 0, 0), **options_spec)

    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
    return metadata 

def setup(app):
    setup.app = app

    # Add visit/depart methods to HTML-Translator:
    def visit_latex_math_html(self, node):
        source = self.document.attributes['source']
        self.body.append(latex2html(node, source))

    def depart_latex_math_html(self, node):
        pass

    # Add visit/depart methods to LaTeX-Translator:
    def visit_latex_math_latex(self, node):
        inline = isinstance(node.parent, nodes.TextElement)
        if inline:
            self.body.append('$%s$' % node['latex'])
        else:
            self.body.extend(['\\begin{equation}',
                              node['latex'],
                              '\\end{equation}'])

    def depart_latex_math_latex(self, node):
        pass

    app.add_node(latex_math,
                 html=(visit_latex_math_html, depart_latex_math_html),
                 latex=(visit_latex_math_latex, depart_latex_math_latex))
    app.add_role('mathmpl', math_role)
    app.add_directive('mathmpl', MathDirective)
    if sphinx.version_info < (1, 8):
        app.add_role('math', math_role)
        app.add_directive('math', MathDirective)

    metadata = {'parallel_read_safe': True, 'parallel_write_safe': True}
    return metadata 

def setup(app):
    app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))

    if sphinx.version_info >= (1, 8, 0):
        # Add Sphinx message catalog for newer versions of Sphinx
        # See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
        rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
        app.add_message_catalog('sphinx', rtd_locale_path) 

def test_title_from_content_scenarios(app, status, warning):

    # Somehow the xml-tree in extract_needs_from_html() works not correctly with py37 and specific
    # extracts, which are needed for sphinx >3.0 only.
    # Everything with Py3.8 is fine again and also Py3.7 with sphinx<3 works here.
    if sys.version_info[0] == 3 and sys.version_info[1] == 7 and sphinx.version_info[0] >= 3:
        return True

    app.build()

    html = Path(app.outdir, 'index.html').read_text()
    needs = extract_needs_from_html(html)

    assert needs[0].id == 'R_12345'
    assert needs[0].title == 'Scenario 1 Title'

    assert needs[1].id is not None
    assert needs[1].title == 'Scenario 2 Title'

    assert needs[2].id == 'R_12346'
    assert needs[2].title == 'Scenario 3 Title'

    assert needs[3].id is not None
    assert needs[3].title == 'Scenario 4 Title'

    assert needs[4].id == 'R_12347'
    assert needs[4].title == 'Title is first sentence'

    assert needs[5].id is not None
    assert needs[5].title == 'Title should be first sentence'

    # The handling of the ellipses character varies between Sphinx versions
    # so we're ignoring it in our comparisons.
    assert needs[6].id is not None
    assert needs[6].title == 'First sentence will be title, but elided since ...'

    assert needs[7].id == 'R_12348'
    assert needs[7].title == 'First sentence will be title, but elided since ...'

    assert needs[8].id == 'R_12349'
    assert needs[8].title == 'Title matches this'

    assert needs[9].id is not None
    assert needs[9].title == 'Title should match this'

    assert needs[10].id == 'R_12350'
    assert needs[10].title == 'First sentence is really long so this should be...'

    assert needs[11].id is not None
    assert needs[11].title == 'First sentence is really long so this should be...' 

def test_title_optional_scenarios(app, status, warning):

    # Somehow the xml-tree in extract_needs_from_html() works not correctly with py37 and specific
    # extracts, which are needed for sphinx >3.0 only.
    # Everything with Py3.8 is fine again and also Py3.7 with sphinx<3 works here.
    if sys.version_info[0] == 3 and sys.version_info[1] == 7 and sphinx.version_info[0] >= 3:
        return True

    app.build()

    html = Path(app.outdir, 'index.html').read_text()
    needs = extract_needs_from_html(html)

    assert needs[0].id == 'R_12345'
    assert needs[0].title == 'Scenario 1 Title'

    assert needs[1].id is not None
    assert needs[1].title == 'Scenario 2 Title'

    assert needs[2].id == 'R_12346'
    assert needs[2].title == 'Scenario 3 Title'

    assert needs[3].id is not None
    assert needs[3].title == 'Scenario 4 Title'

    assert needs[4].id == 'R_12347'
    assert needs[4].title is None

    assert needs[5].id is not None
    assert needs[5].title is None

    assert needs[6].id == 'R_12348'
    assert needs[6].title == 'Title matches this'

    assert needs[7].id is not None
    assert needs[7].title == 'Title should match this'

    assert needs[8].id == 'R_12349'
    assert needs[8].title == 'First sentence is really long so this should be...'

    assert needs[9].id is not None
    assert needs[9].title == 'First sentence is really long so this should be...' 

def check_set(PATH, BUILDER):
    if sys.version_info.major == 2:
        GENERATED_IPYNB_FILES = python27_glob(PATH+"/_build/" + BUILDER + "/", "*.ipynb")
        GENERATED_IPYNB_FILES = [fl for fl in GENERATED_IPYNB_FILES if "/executed/" not in fl]      #Only compare Generated Versions (not Executed)
        ref_files = python27_glob(PATH + "/ipynb/", "*.ipynb")
        REFERENCE_IPYNB_FILES = [fl.split("ipynb/")[-1] for fl in ref_files] 
    else:
        GENERATED_IPYNB_FILES = glob.glob(PATH + "/_build/" + BUILDER + "/**/*.ipynb", recursive=True)
        GENERATED_IPYNB_FILES = [fl for fl in GENERATED_IPYNB_FILES if "/executed/" not in fl]      #Only compare Generated Versions (not Executed)
        ref_files = glob.glob(PATH + "/ipynb/**/*.ipynb", recursive=True)
        REFERENCE_IPYNB_FILES = [fl.split("ipynb/")[-1] for fl in ref_files]
    failed = 0
    for fl in GENERATED_IPYNB_FILES:
        flname = fl.split(BUILDER + "/")[-1]
        #Check for Sphinx Version Specific Excludes
        SKIP = False
        if SPHINX_VERSION[0] in SPHINX_VERSION_EXCLUDE.keys():
            exclude_patterns = SPHINX_VERSION_EXCLUDE[SPHINX_VERSION[0]]
            for pattern in exclude_patterns:
                pattern = re.compile(pattern)
                if pattern.search(flname):
                    print("Excluding: {} (due to SPHINX_VERSION_EXCLUDE)".format(fl))
                    SKIP = True
        if SKIP:
            continue
        else:
            print("Testing {} ...".format(fl))
            if flname not in REFERENCE_IPYNB_FILES:
                print("[FAIL] Notebook {} has no matching test case in ipynb/".format(flname))
                failed += 1
                continue
            nb1 = nbformat.read(fl, NB_VERSION)
            nb2 = nbformat.read(os.path.join(PATH+"/ipynb", flname), NB_VERSION)
            diff = diff_notebooks(nb1, nb2)
            if len(diff) != 0:
                print("[FAIL] {} and {} are different:".format(
                    fl, os.path.join("ipynb", flname)))
                print(diff)
                failed += 1
    return failed

#-Main-#