diff --git a/CHANGES b/CHANGES index 4b4447c5e..aaf7cc5c9 100644 --- a/CHANGES +++ b/CHANGES @@ -71,6 +71,10 @@ Features added Bugs fixed ---------- +* #3821: Failed to import sphinx.util.compat with docutils-0.14rc1 +* #3829: sphinx-quickstart template is incomplete regarding use of alabaster +* #3772: 'str object' has no attribute 'filename' + Testing -------- @@ -97,7 +101,6 @@ Bugs fixed * #3770: Build fails when a "code-block" has the option emphasize-lines and the number indicated is higher than the number of lines * #3774: Incremental HTML building broken when using citations -* #3772: 'str object' has no attribute 'filename' * #3763: got epubcheck validations error if epub_cover is set * #3779: 'ImportError' in sphinx.ext.autodoc due to broken 'sys.meta_path'. Thanks to Tatiana Tereshchenko. @@ -319,8 +322,8 @@ Deprecated 1.6b1 -* ``sphinx.util.compat.Directive`` class is now deprecated. Please use - ``docutils.parsers.rst.Directive`` instead. +* ``sphinx.util.compat.Directive`` class is now deprecated. Please use instead + ``docutils.parsers.rst.Directive`` * ``sphinx.util.compat.docutils_version`` is now deprecated * #2367: ``Sphinx.warn()``, ``Sphinx.info()`` and other logging methods are now deprecated. Please use ``sphinx.util.logging`` (:ref:`logging-api`) instead. diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 3a46dc9b5..4438e2838 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -205,8 +205,8 @@ The parts of messages in Sphinx that go into builds are translated into several locales. The translations are kept as gettext ``.po`` files translated from the master template ``sphinx/locale/sphinx.pot``. -Sphinx uses `Babel `_ to extract messages and -maintain the catalog files. It is integrated in ``setup.py``: +Sphinx uses `Babel `_ to extract messages +and maintain the catalog files. It is integrated in ``setup.py``: * Use ``python setup.py extract_messages`` to update the ``.pot`` template. * Use ``python setup.py update_catalog`` to update all existing language @@ -279,7 +279,7 @@ Debugging Tips * JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``) are generated by this `modified snowballcode generator `_. - Generated `JSX `_ files are + Generated `JSX `_ files are in `this repository `_. You can get the resulting JavaScript files using the following command:: diff --git a/LICENSE b/LICENSE index aa87ad898..a2783ab3f 100644 --- a/LICENSE +++ b/LICENSE @@ -96,7 +96,7 @@ is available under the following license: SmartyPants_ license:: Copyright (c) 2003 John Gruber - (http://daringfireball.net/) + (https://daringfireball.net/projects/smartypants/) All rights reserved. Redistribution and use in source and binary forms, with or without @@ -196,7 +196,7 @@ The included JQuery JavaScript library is available under the MIT license: ---------------------------------------------------------------------- -Copyright (c) 2008 John Resig, http://jquery.com/ +Copyright (c) 2008 John Resig, https://jquery.com/ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the diff --git a/README.rst b/README.rst index e903fbad1..1e027ec8e 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ .. image:: https://img.shields.io/pypi/v/sphinx.svg - :target: http://pypi.python.org/pypi/sphinx + :target: https://pypi.python.org/pypi/Sphinx .. image:: https://readthedocs.org/projects/sphinx/badge/ :target: http://www.sphinx-doc.org/ :alt: Documentation Status diff --git a/babel.cfg b/babel.cfg index caf199e80..a57e0ac09 100644 --- a/babel.cfg +++ b/babel.cfg @@ -1,7 +1,7 @@ -# How setup this file -# http://babel.edgewall.org/wiki/Documentation/setup.html +# How to setup this file +# http://babel.pocoo.org/en/latest/installation.html # this file description: -# http://babel.edgewall.org/wiki/Documentation/messages.html#extraction-method-mapping-and-configuration +# http://babel.pocoo.org/en/latest/messages.html # Extraction from Python source files [python: **.py] diff --git a/doc/builders.rst b/doc/builders.rst index fcd0df091..01c4b2950 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -84,7 +84,7 @@ The builder's "name" must be given to the **-b** command-line option of .. autoattribute:: supported_image_types - .. _Qt help: http://doc.qt.io/qt-4.8/qthelp-framework.html + .. _Qt help: https://doc.qt.io/qt-4.8/qthelp-framework.html .. module:: sphinx.builders.applehelp .. class:: AppleHelpBuilder @@ -209,7 +209,7 @@ The builder's "name" must be given to the **-b** command-line option of Note that a direct PDF builder using ReportLab is available in `rst2pdf `_ version 0.12 or greater. You need to add ``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is -``pdf``. Refer to the `rst2pdf manual `_ +``pdf``. Refer to the `rst2pdf manual `_ for details. .. module:: sphinx.builders.text @@ -255,7 +255,7 @@ for details. the terminal-based program :program:`info`. See :ref:`texinfo-faq` for more details. The Texinfo format is the official documentation system used by the GNU project. More information on Texinfo can be found at - ``_. + ``_. .. autoattribute:: name diff --git a/doc/develop.rst b/doc/develop.rst index 2f14c945f..4fc7792f7 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -27,19 +27,27 @@ releases on PyPI, others you can install from a checkout. This is the current list of contributed extensions in that repository: -- aafig: render embedded ASCII art as nice images using aafigure_. +- aafig: render embedded ASCII art as nice images using aafigure_ - actdiag: embed activity diagrams by using actdiag_ - adadomain: an extension for Ada support (Sphinx 1.0 needed) - ansi: parse ANSI color sequences inside documents -- autorun: Execute code in a ``runblock`` directive. +- argdoc: automatically generate documentation for command-line arguments, descriptions, and help text +- astah: embed diagram by using astah +- autoanysrc: Gather reST documentation from any source files +- autorun: Execute code in a ``runblock`` directive - blockdiag: embed block diagrams by using blockdiag_ +- cacoo: embed diagram from Cacoo +- cf3domain: a domain for CFEngine 3 policies +- cheader: The missing c:header directive for Sphinx's built-in C domain - cheeseshop: easily link to PyPI packages -- clearquest: create tables from ClearQuest_ queries. +- clearquest: create tables from ClearQuest_ queries - cmakedomain_: a domain for CMake_ -- coffeedomain: a domain for (auto)documenting CoffeeScript source code. -- context: a builder for ConTeXt. +- coffeedomain: a domain for (auto)documenting CoffeeScript source code +- context: a builder for ConTeXt +- disqus: embed Disqus comments in documents +- documentedlist: converts a Python list to a table in the generated documentation - doxylink: Link to external Doxygen-generated HTML documentation -- domaintools_: A tool for easy domain creation. +- domaintools_: A tool for easy domain creation - email: obfuscate email addresses - erlangdomain: an extension for Erlang support (Sphinx 1.0 needed) - exceltable: embed Excel spreadsheets into documents using exceltable_ @@ -47,47 +55,49 @@ This is the current list of contributed extensions in that repository: from your site content - findanything_: an extension to add Sublime Text 2-like findanything panels to your documentation to find pages, sections and index entries while typing -- gnuplot: produces images using gnuplot_ language. +- gnuplot: produces images using gnuplot_ language - googleanalytics: track web visitor statistics by using `Google Analytics`_ - googlechart: embed charts by using `Google Chart`_ - googlemaps: embed maps by using `Google Maps`_ -- httpdomain: a domain for documenting RESTful HTTP APIs. +- httpdomain: a domain for documenting RESTful HTTP APIs - hyphenator: client-side hyphenation of HTML using hyphenator_ +- imgur: embed Imgur images, albums, and metadata in documents - inlinesyntaxhighlight_: inline syntax highlighting - lassodomain: a domain for documenting Lasso_ source code -- libreoffice: an extension to include any drawing supported by LibreOffice (e.g. odg, vsd, ...). -- lilypond: an extension inserting music scripts from Lilypond_ in PNG format. +- libreoffice: an extension to include any drawing supported by LibreOffice (e.g. odg, vsd, ...) +- lilypond: an extension inserting music scripts from Lilypond_ in PNG format - makedomain_: a domain for `GNU Make`_ -- matlabdomain: document MATLAB_ code. -- mockautodoc: mock imports. -- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s. -- napoleon: supports `Google style`_ and `NumPy style`_ docstrings. +- matlabdomain: document MATLAB_ code +- mockautodoc: mock imports +- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s +- napoleon: supports `Google style`_ and `NumPy style`_ docstrings - nicovideo: embed videos from nicovideo - nwdiag: embed network diagrams by using nwdiag_ - omegat: support tools to collaborate with OmegaT_ (Sphinx 1.1 needed) - osaka: convert standard Japanese doc to Osaka dialect (this is a joke extension) -- paverutils: an alternate integration of Sphinx with Paver_. +- paverutils: an alternate integration of Sphinx with Paver_ - phpdomain: an extension for PHP support - plantuml: embed UML diagram by using PlantUML_ - py_directive: Execute python code in a ``py`` directive and return a math - node. -- rawfiles: copy raw files, like a CNAME. + node +- rawfiles: copy raw files, like a CNAME - requirements: declare requirements wherever you need (e.g. in test docstrings), mark statuses and collect them in a single list -- restbuilder: a builder for reST (reStructuredText) files. +- restbuilder: a builder for reST (reStructuredText) files - rubydomain: an extension for Ruby support (Sphinx 1.0 needed) - sadisplay: display SqlAlchemy model sadisplay_ - sdedit: an extension inserting sequence diagram by using Quick Sequence Diagram Editor (sdedit_) - seqdiag: embed sequence diagrams by using seqdiag_ -- slide: embed presentation slides on slideshare_ and other sites. +- slide: embed presentation slides on slideshare_ and other sites - swf_: embed flash files -- sword: an extension inserting Bible verses from Sword_. -- tikz: draw pictures with the `TikZ/PGF LaTeX package`_. +- sword: an extension inserting Bible verses from Sword_ +- tikz: draw pictures with the `TikZ/PGF LaTeX package`_ - traclinks: create TracLinks_ to a Trac_ instance from within Sphinx +- versioning: Sphinx extension that allows building versioned docs for self-hosting - whooshindex: whoosh indexer extension - youtube: embed videos from YouTube_ -- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_. +- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_ See the :ref:`extension tutorial ` on getting started with writing your diff --git a/doc/domains.rst b/doc/domains.rst index ce6ef9e70..4eb3a581c 100644 --- a/doc/domains.rst +++ b/doc/domains.rst @@ -34,8 +34,8 @@ documentation wants to refer to e.g. C++ and Python classes. It also means that extensions that support the documentation of whole new languages are much easier to write. -This section describes what the domains that come with Sphinx provide. The -domain API is documented as well, in the section :ref:`domain-api`. +This section describes what the domains that are included with Sphinx provide. +The domain API is documented as well, in the section :ref:`domain-api`. .. _basic-domain-markup: diff --git a/doc/extensions.rst b/doc/extensions.rst index afd211c34..c005218e8 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -4,7 +4,7 @@ Sphinx Extensions ================= Since many projects will need special features in their documentation, Sphinx -allows to add "extensions" to the build process, each of which can modify almost +allows adding "extensions" to the build process, each of which can modify almost any aspect of document processing. This chapter describes the extensions bundled with Sphinx. For the API diff --git a/doc/faq.rst b/doc/faq.rst index 5924f5f68..133614ef2 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -140,7 +140,7 @@ The following list gives some hints for the creation of epub files: are often cut at the right margin. The default Courier font (or variant) is quite wide and you can only display up to 60 characters on a line. If you replace it with a narrower font, you can get more characters on a line. You - may even use `FontForge `_ and create + may even use `FontForge `_ and create narrow variants of some free font. In my case I get up to 70 characters on a line. @@ -148,7 +148,7 @@ The following list gives some hints for the creation of epub files: * Test the created epubs. You can use several alternatives. The ones I am aware of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS), - and Bookworm_. For bookworm you can download the source from + and Bookworm_. For Bookworm, you can download the source from https://code.google.com/archive/p/threepress and run your own local server. * Large floating divs are not displayed properly. @@ -176,7 +176,7 @@ The following list gives some hints for the creation of epub files: $ make epub $ kindlegen _build/epub/yourdoc.epub - kindlegen commands doesn't accept documents that have section + The kindlegen command doesn't accept documents that have section titles surrounding ``toctree`` directive: .. code-block:: rst @@ -191,18 +191,18 @@ The following list gives some hints for the creation of epub files: Section After Toc Tree ====================== - kindlegen assumes all documents order in line, but resulting document - has complecated order for kindlegen:: + kindlegen assumes all documents order in line, but the resulting document + has complicated order for kindlegen:: ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml`` - If you got the following error, fix document structure:: + If you get the following error, fix your document structure:: Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title) Error(prcgen):E24001: The table of content could not be built. .. _Epubcheck: https://github.com/IDPF/epubcheck -.. _Calibre: http://calibre-ebook.com/ +.. _Calibre: https://calibre-ebook.com/ .. _FBreader: https://fbreader.org/ .. _Bookworm: http://www.oreilly.com/bookworm/index.html .. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211 @@ -239,7 +239,7 @@ The exact behavior of how Emacs displays references is dependent on the variable both the ``*note:`` part and the ``target-id``. This is generally the best way to view Sphinx-based documents since they often make frequent use of links and do not take this limitation into account. However, changing this variable -affects how all Info documents are displayed and most due take this behavior +affects how all Info documents are displayed and most do take this behavior into account. If you want Emacs to display Info files produced by Sphinx using the value diff --git a/doc/latex.rst b/doc/latex.rst index fc872342a..1c6b5202d 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -57,7 +57,7 @@ in Python string literals to reach latex.) For example:: } latex_show_urls = 'footnote' -.. the above was tested on Sphinx's own 1.5a2 documentation with good effect ! +.. the above was tested on Sphinx's own 1.5a2 documentation with good effect! .. highlight:: latex @@ -92,8 +92,8 @@ string of ``key=value`` instructions:: key1=value1,key2=value2, ... -- if a key is repeated, it is its last occurence which counts, -- spaces around the commas and equal signs are ignored. +- if a key is repeated, it is its last occurence which is used +- spaces around the commas and equal signs are ignored If non-empty, it will be passed as argument to the ``\sphinxsetup`` command:: @@ -148,7 +148,7 @@ Here are the currently available options together with their default values. .. attention:: - LaTeX requires for keys with Boolean values to use **lowercase** ``true`` or + LaTeX requires that keys with Boolean values use **lowercase** ``true`` or ``false``. .. _latexsphinxsetuphmargin: @@ -215,8 +215,8 @@ Here are the currently available options together with their default values. .. (comment) It is theoretically possible to customize this even more and decide at which characters a line-break can occur and whether - before or after, but this is accessible currently only by re-defining some - macros with complicated LaTeX syntax from :file:`sphinx.sty`. + before or after, but this is accessible currently only by re-defining + some macros with complicated LaTeX syntax from :file:`sphinx.sty`. ``parsedliteralwraps`` default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's @@ -230,8 +230,7 @@ Here are the currently available options together with their default values. potential break-points (additionally to those allowed by LaTeX at spaces or for hyphenation) are currently inserted only after the characters ``. , ; ? ! /``. Due to TeX internals, white space in the line will be - stretched - (or shrinked) in order to accomodate the linebreak. + stretched (or shrunk) in order to accomodate the linebreak. .. versionadded:: 1.5 set this option value to ``false`` to recover former behaviour. diff --git a/doc/setuptools.rst b/doc/setuptools.rst index a8666a0bd..dab25fc59 100644 --- a/doc/setuptools.rst +++ b/doc/setuptools.rst @@ -10,7 +10,7 @@ Using setuptools integration ---------------------------- The Sphinx build can then be triggered from distutils, and some Sphinx -options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx own +options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx's own configuration file. For instance, from ``setup.py``:: diff --git a/doc/theming.rst b/doc/theming.rst index 711d0ae72..c8cad2ba2 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -119,10 +119,12 @@ These themes are: * **alabaster** -- `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz (especially as used in his Requests project), which was itself originally based on - @mitsuhiko's theme used for Flask & related projects. You can get options information - at `Alabaster theme`_ page. + @mitsuhiko's theme used for Flask & related projects. + Check out at its `installation page`_ how to set up properly + :confval:`html_sidebars` for its use. .. _Alabaster theme: https://pypi.python.org/pypi/alabaster + .. _installation page: http://alabaster.readthedocs.io/en/latest/installation.html * **classic** -- This is the classic theme, which looks like `the Python 2 documentation `_. It can be customized via diff --git a/sphinx/templates/quickstart/conf.py_t b/sphinx/templates/quickstart/conf.py_t index ba8812cfe..a8efc1803 100644 --- a/sphinx/templates/quickstart/conf.py_t +++ b/sphinx/templates/quickstart/conf.py_t @@ -96,6 +96,18 @@ todo_include_todos = {{ ext_todo }} # html_theme = 'alabaster' +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'about.html', + 'navigation.html', + # 'relations.html', # hidden by alabaster css anyway + 'searchbox.html', + # 'donate.html', + ] +} + + # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html index c7807b1cd..c7312ffd0 100644 --- a/sphinx/themes/basic/layout.html +++ b/sphinx/themes/basic/layout.html @@ -106,7 +106,11 @@ {%- for css in css_files %} + {%- if css|attr("rel") %} + {%- else %} + + {%- endif %} {%- endfor %} {%- endmacro %} diff --git a/sphinx/util/smartypants.py b/sphinx/util/smartypants.py index 2c4fe7d92..10e4d82ea 100644 --- a/sphinx/util/smartypants.py +++ b/sphinx/util/smartypants.py @@ -143,12 +143,23 @@ def educateQuotes(text, language='en'): def educate_tokens(text_tokens, attr='1', language='en'): # type: (Iterable[Tuple[str, unicode]], unicode, unicode) -> Iterator """Return iterator that "educates" the items of `text_tokens`. + + This is modified to intercept the ``attr='2'`` as it was used by the + Docutils 0.13.1 SmartQuotes transform in a hard coded way. Docutils 0.14 + uses ``'qDe'``` and is configurable, and its choice is backported here + for use by Sphinx with earlier Docutils releases. Similarly ``'1'`` is + replaced by ``'qde'``. + + Use ``attr='qDbe'``, resp. ``'qdbe'`` to recover Docutils effect of ``'2'``, + resp. ``'1'``. + + refs: https://sourceforge.net/p/docutils/mailman/message/35869025/ """ # Parse attributes: # 0 : do nothing - # 1 : set all - # 2 : set all, using old school en- and em- dash shortcuts + # 1 : set all (but backticks) + # 2 : set all (but backticks), using old school en- and em- dash shortcuts # 3 : set all, using inverted old school en and em- dash shortcuts # # q : quotes @@ -171,13 +182,13 @@ def educate_tokens(text_tokens, attr='1', language='en'): pass elif attr == "1": # Do everything, turn all options on. do_quotes = True - do_backticks = 1 + # do_backticks = 1 do_dashes = 1 do_ellipses = True elif attr == "2": # Do everything, turn all options on, use old school dash shorthand. do_quotes = True - do_backticks = 1 + # do_backticks = 1 do_dashes = 2 do_ellipses = True elif attr == "3":