弃用 APIs

在开发Sphinx时,我们始终注意API的兼容性。 但是,有时候,由于某些原因需要改变界面。 在这种情况下,我们已将其标记为已弃用。它们保留在两个主要版本中(有关详细信息,请参阅 弃用政策)。

以下是不推荐使用的接口列表。

deprecated APIs

目标

弃用

(将)删除

备择方案

sphinx.builders.latex.LaTeXBuilder.apply_transforms()

2.1

4.0

N/A

sphinx.directives.Acks

2.1

4.0

sphinx.directives.other.Acks

sphinx.directives.Author

2.1

4.0

sphinx.directives.other.Author

sphinx.directives.Centered

2.1

4.0

sphinx.directives.other.Centered

sphinx.directives.Class

2.1

4.0

sphinx.directives.other.Class

sphinx.directives.CodeBlock

2.1

4.0

sphinx.directives.code.CodeBlock

sphinx.directives.Figure

2.1

4.0

sphinx.directives.patches.Figure

sphinx.directives.HList

2.1

4.0

sphinx.directives.other.HList

sphinx.directives.Highlight

2.1

4.0

sphinx.directives.code.Highlight

sphinx.directives.Include

2.1

4.0

sphinx.directives.other.Include

sphinx.directives.Index

2.1

4.0

sphinx.directives.other.Index

sphinx.directives.LiteralInclude

2.1

4.0

sphinx.directives.code.LiteralInclude

sphinx.directives.Meta

2.1

4.0

sphinx.directives.patches.Meta

sphinx.directives.Only

2.1

4.0

sphinx.directives.other.Only

sphinx.directives.SeeAlso

2.1

4.0

sphinx.directives.other.SeeAlso

sphinx.directives.TabularColumns

2.1

4.0

sphinx.directives.other.TabularColumns

sphinx.directives.TocTree

2.1

4.0

sphinx.directives.other.TocTree

sphinx.directives.VersionChange

2.1

4.0

sphinx.directives.other.VersionChange

sphinx.environment.NoUri

2.1

4.0

sphinx.errors.NoUri

sphinx.ext.autodoc.importer.MockFinder

2.1

4.0

sphinx.ext.autodoc.mock.MockFinder

sphinx.ext.autodoc.importer.MockLoader

2.1

4.0

sphinx.ext.autodoc.mock.MockLoader

sphinx.ext.autodoc.importer.mock()

2.1

4.0

sphinx.ext.autodoc.mock.mock()

sphinx.ext.autosummary.autolink_role()

2.1

4.0

sphinx.ext.autosummary.AutoLink

sphinx.util.node.find_source_node()

2.1

4.0

sphinx.util.node.get_node_source()

sphinx.util.i18n.find_catalog()

2.1

4.0

sphinx.util.i18n.docname_to_domain()

sphinx.util.i18n.find_catalog_files()

2.1

4.0

sphinx.util.i18n.CatalogRepository

sphinx.util.i18n.find_catalog_source_files()

2.1

4.0

sphinx.util.i18n.CatalogRepository

encoding argument of autodoc.Documenter.get_doc(), autodoc.DocstringSignatureMixin.get_doc(), autodoc.DocstringSignatureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc()

2.0

4.0

N/A

arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_container(), EpubBuilder.build_content(), EpubBuilder.build_toc() and EpubBuilder.build_epub()

2.0

4.0

N/A

arguments of Epub3Builder.build_navigation_doc()

2.0

4.0

N/A

nodetype argument of sphinx.search.WordCollector.is_meta_keywords()

2.0

4.0

N/A

suffix argument of BuildEnvironment.doc2path()

2.0

4.0

N/A

string style base argument of BuildEnvironment.doc2path()

2.0

4.0

os.path.join()

sphinx.addnodes.abbreviation

2.0

4.0

docutils.nodes.abbreviation

sphinx.builders.applehelp

2.0

4.0

sphinxcontrib.applehelp

sphinx.builders.devhelp

2.0

4.0

sphinxcontrib.devhelp

sphinx.builders.epub3.Epub3Builder.validate_config_value()

2.0

4.0

sphinx.builders.epub3.validate_config_values()

sphinx.builders.html.JSONHTMLBuilder

2.0

4.0

sphinx.builders.serializinghtml.JSONHTMLBuilder

sphinx.builders.html.PickleHTMLBuilder

2.0

4.0

sphinx.builders.serializinghtml.PickleHTMLBuilder

sphinx.builders.html.SerializingHTMLBuilder

2.0

4.0

sphinx.builders.serializinghtml.SerializingHTMLBuilder

sphinx.builders.html.SingleFileHTMLBuilder

2.0

4.0

sphinx.builders.singlehtml.SingleFileHTMLBuilder

sphinx.builders.html.WebHTMLBuilder

2.0

4.0

sphinx.builders.serializinghtml.PickleHTMLBuilder

sphinx.builders.htmlhelp

2.0

4.0

sphinxcontrib.htmlhelp

sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()

2.0

4.0

open()

sphinx.builders.qthelp

2.0

4.0

sphinxcontrib.qthelp

sphinx.cmd.quickstart.term_decode()

2.0

4.0

N/A

sphinx.cmd.quickstart.TERM_ENCODING

2.0

4.0

sys.stdin.encoding

sphinx.config.check_unicode()

2.0

4.0

N/A

sphinx.config.string_classes

2.0

4.0

[str]

sphinx.domains.cpp.DefinitionError.description

2.0

4.0

str(exc)

sphinx.domains.cpp.NoOldIdError.description

2.0

4.0

str(exc)

sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded

2.0

4.0

str(exc)

sphinx.ext.autosummary.Autosummary.warn()

2.0

4.0

N/A

sphinx.ext.autosummary.Autosummary.genopt

2.0

4.0

N/A

sphinx.ext.autosummary.Autosummary.warnings

2.0

4.0

N/A

sphinx.ext.autosummary.Autosummary.result

2.0

4.0

N/A

sphinx.ext.doctest.doctest_encode()

2.0

4.0

N/A

sphinx.ext.jsmath

2.0

4.0

sphinxcontrib.jsmath

sphinx.roles.abbr_role()

2.0

4.0

sphinx.roles.Abbreviation

sphinx.roles.emph_literal_role()

2.0

4.0

sphinx.roles.EmphasizedLiteral

sphinx.roles.menusel_role()

2.0

4.0

sphinx.roles.GUILabel or sphinx.roles.MenuSelection

sphinx.roles.index_role()

2.0

4.0

sphinx.roles.Index

sphinx.roles.indexmarkup_role()

2.0

4.0

sphinx.roles.PEP or sphinx.roles.RFC

sphinx.testing.util.remove_unicode_literal()

2.0

4.0

N/A

sphinx.util.attrdict

2.0

4.0

N/A

sphinx.util.force_decode()

2.0

4.0

N/A

sphinx.util.get_matching_docs()

2.0

4.0

sphinx.util.get_matching_files()

sphinx.util.inspect.Parameter

2.0

3.0

N/A

sphinx.util.jsonimpl

2.0

4.0

sphinxcontrib.serializinghtml.jsonimpl

sphinx.util.osutil.EEXIST

2.0

4.0

errno.EEXIST or FileExistsError

sphinx.util.osutil.EINVAL

2.0

4.0

errno.EINVAL

sphinx.util.osutil.ENOENT

2.0

4.0

errno.ENOENT or FileNotFoundError

sphinx.util.osutil.EPIPE

2.0

4.0

errno.ENOENT or BrokenPipeError

sphinx.util.osutil.walk()

2.0

4.0

os.walk()

sphinx.util.pycompat.NoneType

2.0

4.0

sphinx.util.typing.NoneType

sphinx.util.pycompat.TextIOWrapper

2.0

4.0

io.TextIOWrapper

sphinx.util.pycompat.UnicodeMixin

2.0

4.0

N/A

sphinx.util.pycompat.htmlescape()

2.0

4.0

html.escape()

sphinx.util.pycompat.indent()

2.0

4.0

textwrap.indent()

sphinx.util.pycompat.sys_encoding

2.0

4.0

sys.getdefaultencoding()

sphinx.util.pycompat.terminal_safe()

2.0

4.0

sphinx.util.console.terminal_safe()

sphinx.util.pycompat.u

2.0

4.0

N/A

sphinx.util.PeekableIterator

2.0

4.0

N/A

Omitting the filename argument in an overriddent IndexBuilder.feed() method.

2.0

4.0

IndexBuilder.feed(docname, filename, title, doctree)

sphinx.writers.latex.ExtBabel

2.0

4.0

sphinx.builders.latex.util.ExtBabel

sphinx.writers.latex.LaTeXTranslator.babel_defmacro()

2.0

4.0

N/A

sphinx.application.Sphinx._setting_up_extension

2.0

3.0

N/A

The importer argument of sphinx.ext.autodoc.importer._MockModule

2.0

3.0

N/A

sphinx.ext.autodoc.importer._MockImporter

2.0

3.0

N/A

sphinx.io.SphinxBaseFileInput

2.0

3.0

N/A

sphinx.io.SphinxFileInput.supported

2.0

3.0

N/A

sphinx.io.SphinxRSTFileInput

2.0

3.0

N/A

sphinx.registry.SphinxComponentRegistry.add_source_input()

2.0

3.0

N/A

sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()

2.0

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.collect_footnotes()

2.0

4.0

N/A

sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()

2.0

3.0

N/A

sphinx.writers.text.TextTranslator._make_depart_admonition()

2.0

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()

2.0

4.0

N/A

highlightlang

1.8

4.0

highlight

add_stylesheet()

1.8

4.0

add_css_file()

add_javascript()

1.8

4.0

add_js_file()

autodoc_default_flags

1.8

4.0

autodoc_default_options

content arguments of sphinx.util.image.guess_mimetype()

1.8

3.0

N/A

gettext_compact arguments of sphinx.util.i18n.find_catalog_source_files()

1.8

3.0

N/A

sphinx.io.SphinxI18nReader.set_lineno_for_reporter()

1.8

3.0

N/A

sphinx.io.SphinxI18nReader.line

1.8

3.0

N/A

sphinx.directives.other.VersionChanges

1.8

3.0

sphinx.domains.changeset.VersionChanges

sphinx.highlighting.PygmentsBridge.unhighlight()

1.8

3.0

N/A

trim_doctest_flags arguments of sphinx.highlighting.PygmentsBridge

1.8

3.0

N/A

sphinx.ext.mathbase

1.8

3.0

N/A

sphinx.ext.mathbase.MathDomain

1.8

3.0

sphinx.domains.math.MathDomain

sphinx.ext.mathbase.MathDirective

1.8

3.0

sphinx.directives.patches.MathDirective

sphinx.ext.mathbase.math_role()

1.8

3.0

docutils.parsers.rst.roles.math_role()

sphinx.ext.mathbase.setup_math()

1.8

3.0

add_html_math_renderer()

sphinx.ext.mathbase.is_in_section_title()

1.8

3.0

N/A

sphinx.ext.mathbase.get_node_equation_number()

1.8

3.0

sphinx.util.math.get_node_equation_number()

sphinx.ext.mathbase.wrap_displaymath()

1.8

3.0

sphinx.util.math.wrap_displaymath()

sphinx.ext.mathbase.math (node)

1.8

3.0

docutils.nodes.math

sphinx.ext.mathbase.displaymath (node)

1.8

3.0

docutils.nodes.math_block

sphinx.ext.mathbase.eqref (node)

1.8

3.0

sphinx.builders.latex.nodes.math_reference

viewcode_import (config value)

1.8

3.0

viewcode_follow_imported_members

sphinx.writers.latex.Table.caption_footnotetexts

1.8

3.0

N/A

sphinx.writers.latex.Table.header_footnotetexts

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.footnotestack

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.in_container_literal_block

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.next_section_ids

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.restrict_footnote()

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.bibitems

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.hlsettingstack

1.8

3.0

N/A

sphinx.writers.latex.ExtBabel.get_shorthandoff()

1.8

3.0

N/A

sphinx.writers.html.HTMLTranslator.highlightlang()

1.8

3.0

N/A

sphinx.writers.html.HTMLTranslator.highlightlang_base()

1.8

3.0

N/A

sphinx.writers.html.HTMLTranslator.highlightlangopts()

1.8

3.0

N/A

sphinx.writers.html.HTMLTranslator.highlightlinenothreshold()

1.8

3.0

N/A

sphinx.writers.html5.HTMLTranslator.highlightlang()

1.8

3.0

N/A

sphinx.writers.html5.HTMLTranslator.highlightlang_base()

1.8

3.0

N/A

sphinx.writers.html5.HTMLTranslator.highlightlangopts()

1.8

3.0

N/A

sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold()

1.8

3.0

N/A

sphinx.writers.latex.LaTeXTranslator.check_latex_elements()

1.8

3.0

Nothing

sphinx.application.CONFIG_FILENAME

1.8

3.0

sphinx.config.CONFIG_FILENAME

Config.check_unicode()

1.8

3.0

sphinx.config.check_unicode()

Config.check_types()

1.8

3.0

sphinx.config.check_confval_types()

dirname, filename and tags arguments of Config.__init__()

1.8

3.0

Config.read()

The value of html_search_options

1.8

3.0

see html_search_options

sphinx.versioning.prepare()

1.8

3.0

sphinx.versioning.UIDTransform

Sphinx.override_domain()

1.8

3.0

add_domain()

Sphinx.import_object()

1.8

3.0

sphinx.util.import_object()

suffix argument of add_source_parser()

1.8

3.0

add_source_suffix()

BuildEnvironment.load()

1.8

3.0

pickle.load()

BuildEnvironment.loads()

1.8

3.0

pickle.loads()

BuildEnvironment.frompickle()

1.8

3.0

pickle.load()

BuildEnvironment.dump()

1.8

3.0

pickle.dump()

BuildEnvironment.dumps()

1.8

3.0

pickle.dumps()

BuildEnvironment.topickle()

1.8

3.0

pickle.dump()

BuildEnvironment._nitpick_ignore

1.8

3.0

nitpick_ignore

BuildEnvironment.versionchanges

1.8

3.0

N/A

BuildEnvironment.update()

1.8

3.0

Builder.read()

BuildEnvironment.read_doc()

1.8

3.0

Builder.read_doc()

BuildEnvironment._read_serial()

1.8

3.0

Builder.read()

BuildEnvironment._read_parallel()

1.8

3.0

Builder.read()

BuildEnvironment.write_doctree()

1.8

3.0

Builder.write_doctree()

BuildEnvironment.note_versionchange()

1.8

3.0

ChangesDomain.note_changeset()

warn() (template helper function)

1.8

3.0

warning()

source_parsers

1.8

3.0

add_source_parser()

sphinx.util.docutils.directive_helper()

1.8

3.0

Directive class of docutils

sphinx.cmdline

1.8

3.0

sphinx.cmd.build

sphinx.make_mode

1.8

3.0

sphinx.cmd.make_mode

sphinx.locale.l_()

1.8

3.0

sphinx.locale._()

sphinx.locale.lazy_gettext()

1.8

3.0

sphinx.locale._()

sphinx.locale.mygettext()

1.8

3.0

sphinx.locale._()

sphinx.util.copy_static_entry()

1.5

3.0

sphinx.util.fileutil.copy_asset()

sphinx.build_main()

1.7

2.0

sphinx.cmd.build.build_main()

sphinx.ext.intersphinx.debug()

1.7

2.0

sphinx.ext.intersphinx.inspect_main()

sphinx.ext.autodoc.format_annotation()

1.7

2.0

sphinx.util.inspect.Signature

sphinx.ext.autodoc.formatargspec()

1.7

2.0

sphinx.util.inspect.Signature

sphinx.ext.autodoc.AutodocReporter

1.7

2.0

sphinx.util.docutils.switch_source_input()

sphinx.ext.autodoc.add_documenter()

1.7

2.0

add_autodocumenter()

sphinx.ext.autodoc.AutoDirective._register

1.7

2.0

add_autodocumenter()

AutoDirective._special_attrgetters

1.7

2.0

add_autodoc_attrgetter()

Sphinx.warn(), Sphinx.info()

1.6

2.0

记录API

BuildEnvironment.set_warnfunc()

1.6

2.0

记录API

BuildEnvironment.note_toctree()

1.6

2.0

Toctree.note() (in sphinx.environment.adapters.toctree)

BuildEnvironment.get_toc_for()

1.6

2.0

Toctree.get_toc_for() (in sphinx.environment.adapters.toctree)

BuildEnvironment.get_toctree_for()

1.6

2.0

Toctree.get_toctree_for() (in sphinx.environment.adapters.toctree)

BuildEnvironment.create_index()

1.6

2.0

IndexEntries.create_index() (in sphinx.environment.adapters.indexentries)

sphinx.websupport

1.6

2.0

sphinxcontrib-websupport

StandaloneHTMLBuilder.css_files

1.6

2.0

add_stylesheet()

document.settings.gettext_compact

1.8

1.8

gettext_compact

Sphinx.status_iterator()

1.6

1.7

sphinx.util.status_iterator()

Sphinx.old_status_iterator()

1.6

1.7

sphinx.util.old_status_iterator()

Sphinx._directive_helper()

1.6

1.7

sphinx.util.docutils.directive_helper()

sphinx.util.compat.Directive

1.6

1.7

docutils.parsers.rst.Directive

sphinx.util.compat.docutils_version

1.6

1.7

sphinx.util.docutils.__version_info__

注解

在弃用公共API(内部函数和类)时,我们也尽可能遵循该策略。