Python 开发的程序文档工具 —— Sphinx 发布 1.4 版本，Sphinx 简单来说，是一个文档生成工具，用于把reStructuredText 格式的源文件生成诸如HTML, PDF, LaTex一类的格式。编辑者无须亲自处理文本的格式, 程序会自动根据源文件里的设置产生格式, 以及自动生成章节链接等工作。 新版本改进记录包括： Incompatible changes -------------------- * Drop ``PorterStemmer`` package support. Use ``PyStemmer`` instead of ``PorterStemmer`` to accelerate stemming. * sphinx_rtd_theme has become optional. Please install it manually. Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich. * #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer. It enables to take title of roles as an argument of custom macros. * #2022: 'Thumbs.db' and '.DS_Store' are added to `exclude_patterns` default values in conf.py that will be provided on sphinx-quickstart. * #2027, #2208: The ``html_title`` accepts string values only. And The None value cannot be accepted. * ``sphinx.ext.graphviz``: show graph image in inline by default * #2060, #2224: The ``manpage`` role now generate ``sphinx.addnodes.manpage`` node instead of ``sphinx.addnodes.literal_emphasis`` node. * #2022: :confval:`html_extra_path` also copies dotfiles in the extra directory, and refers to :confval:`exclude_patterns` to exclude extra files and directories. * #2300: enhance autoclass:: to use the docstring of __new__ if __init__ method's is missing of empty * #2251: Previously, under glossary directives, multiple terms for one definition are converted into single ``term`` node and the each terms in the term node are separated by ``termsep`` node. In new implementation, each terms are converted into individual ``term`` nodes and ``termsep`` node is removed. By this change, output layout of every builders are changed a bit. * The default highlight language is now Python 3. This means that source code is highlighted as Python 3 (which is mostly a superset of Python 2), and no parsing is attempted to distinguish valid code. To get the old behavior back, add ``highlight_language = "python"`` to conf.py. * `Locale Date Markup Language <http://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns>`_ like ``"MMMM dd, YYYY"`` is default format for `today_fmt` and `html_last_updated_fmt`. However strftime format like ``"%B %d, %Y"`` is also supported for backward compatibility until Sphinx-1.5. Later format will be disabled from Sphinx-1.5. * #2327: `latex_use_parts` is deprecated now. Use `latex_toplevel_sectioning` instead. * #2337: Use ``\url{URL}`` macro instead of ``\href{URL}{URL}`` in LaTeX writer. * #1498: manpage writer: don't make whole of item in definition list bold if it includes strong node. * #582: Remove hint message from quick search box for html output. * #2378: Sphinx now bundles newfloat.sty Features added -------------- * #2092: add todo directive support in napoleon package. * #1962: when adding directives, roles or nodes from an extension, warn if such an element is already present (built-in or added by another extension). * #1909: Add "doc" references to Intersphinx inventories. * C++ type alias support (e.g., ``.. type:: T = int``). * C++ template support for classes, functions, type aliases, and variables (#1729, #1314). * C++, added new scope management directives ``namespace-push`` and ``namespace-pop``. * #1970: Keyboard shortcuts to navigate Next and Previous topics * Intersphinx: Added support for fetching Intersphinx inventories with URLs using HTTP basic auth. * C++, added support for template parameter in function info field lists. * C++, added support for pointers to member (function). * #2113: Allow ``:class:`` option to code-block directive. * #2192: Imgmath (pngmath with svg support). * #2200: Support XeTeX and LuaTeX for the LaTeX builder. * #1906: Use xcolor over color for \fcolorbox where available for LaTeX output. * #2216: Texinputs makefile improvements. * #2170: Support for Chinese language search index. * #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages * #1030: Make page reference names for latex_show_pagerefs translatable * #2162: Add Sphinx.add_source_parser() to add source_suffix and source_parsers from extension * #2207: Add sphinx.parsers.Parser class; a base class for new parsers * #656: Add ``graphviz_dot`` option to graphviz directives to switch the ``dot`` command * #1939: Added the ``dummy`` builder: syntax check without output. * #2230: Add ``math_number_all`` option to number all displayed math in math extensions * #2235: ``needs_sphinx`` supports micro version comparison * #2282: Add "language" attribute to html tag in the "basic" theme * #1779: Add EPUB 3 builder * #1751: Add :confval:`todo_link_only` to avoid file path and line indication on :rst:dir:`todolist`. Thanks to Francesco Montesano. * #2199: Use ``imagesize`` package to obtain size of images. * #1099: Add configurable retries to the linkcheck builder. Thanks to Alex Gaynor. Also don't check anchors starting with ``!``. * #2300: enhance autoclass:: to use the docstring of __new__ if __init__ method's is missing of empty * #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for numfig feature * #1286, #2099: Add ``sphinx.ext.autosectionlabel`` extension to allow reference sections using its title. Thanks to Tadhg O'Higgins. * #1854: Allow to choose Janome for Japanese splitter. * #1853: support custom text splitter on html search with ``language='ja'``. * #2320: classifier of glossary terms can be used for index entries grouping key. The classifier also be used for translation. See also :ref:`glossary-directive`. * #2308: Define ``\tablecontinued`` macro to redefine the style of continued label for longtables. * Select an image by similarity if multiple images are globbed by ``.. image:: filename.*`` * #1921: Support figure substitutions by :confval:`language` and :confval:`figure_language_filename` * #2245: Add ``latex_elements["passoptionstopackages"]`` option to call PassOptionsToPackages in early stage of preambles. * #2340: Math extension: support alignment of multiple equations for MathJAX. * #2338: Define ``\titleref`` macro to redefine the style of ``title-reference`` roles. * Define ``\menuselection`` and ``\accelerator`` macros to redefine the style of `menuselection` roles. * Define ``\crossref`` macro to redefine the style of references * #2301: Texts in the classic html theme should be hyphenated. * #2355: Define ``\termref`` macro to redefine the style of ``term`` roles. * Add :confval:`suppress_warnings` to suppress arbitrary warning message (experimental) * #2229: Fix no warning is given for unknown options * #2327: Add `latex_toplevel_sectioning` to switch the top level sectioning of LaTeX document. Bugs fixed ---------- * #1913: C++, fix assert bug for enumerators in next-to-global and global scope. * C++, fix parsing of 'signed char' and 'unsigned char' as types. * C++, add missing support for 'friend' functions. * C++, add missing support for virtual base classes (thanks to Rapptz). * C++, add support for final classes. * C++, fix parsing of types prefixed with 'enum'. * #2023: Dutch search support uses Danish stemming info. * C++, add support for user-defined literals. * #1804: Now html output wraps overflowed long-line-text in the sidebar. Thanks to Hassen ben tanfous. * #2183: Fix porterstemmer causes ``make json`` to fail. * #1899: Ensure list is sent to OptParse. * #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx package option). * #2165, #2218: Remove faulty and non-need conditional from sphinx.sty. * Fix broken LaTeX code is generated if unknown language is given * #1944: Fix rst_prolog breaks file-wide metadata * #2074: make gettext should use canonical relative paths for .pot. Thanks to anatoly techtonik. * #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError * #2251: Line breaks in .rst files are transferred to .pot files in a wrong way. * #794: Fix date formatting in latex output is not localized * Remove ``image/gif`` from supported_image_types of LaTeX writer (#2272) * Fix ValueError is raised if LANGUAGE is empty string * Fix unpack warning is shown when the directives generated from ``Sphinx.add_crossref_type`` is used * The default highlight language is now ``default``. This means that source code is highlighted as Python 3 (which is mostly a superset of Python 2) if possible. To get the old behavior back, add ``highlight_language = "python"`` to conf.py. * #2329: Refresh environment forcely if source directory has changed. * #2331: Fix code-blocks are filled by block in dvi; remove ``xcdraw`` option from xcolor package * Fix the confval type checker emits warnings if unicode is given to confvals which expects string value * #2360: Fix numref in LaTeX output is broken * #2361: Fix additional paragraphs inside the "compound" directive are indented * #2364: Fix KeyError 'rootSymbol' on Sphinx upgrade from older version. * #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer. * #2368: Ignore emacs lock files like ``.#foo.rst`` by default. * #2262: literal_block and its caption has been separated by pagebreak in LaTeX output. * #2319: Fix table counter is overrided by code-block's in LaTeX. Thanks to jfbu. * Fix unpack warning if combinated with 3rd party domain extensions. * #1153: Fix figures in sidebar causes latex build error. * #2358: Fix user-preamble could not override the tocdepth definition. * #2358: Redece tocdepth if ``part`` or ``chapter`` is used for top_sectionlevel. * #2351: Fix footnote spacing * #2363: Fix ``toctree()`` in templates generates broken links in SingleHTMLBuilder. * #2366: Fix empty hyperref is generated on toctree in HTML builder. Documentation ------------- * #1757: Fix for usage of :confval:`html_last_updated_fmt`. Thanks to Ralf Hemmecke. Sphinx 1.4 发布，Python 开发程序文档工具下载地址
