From 26bf2d5fc0a0a0411da97545e9175bd6c1fc86e9 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 15 Dec 2016 11:47:17 +0900 Subject: [PATCH 1/9] Closes #3194: Refer the $MAKE environment variable to determine ``make`` command --- CHANGES | 1 + doc/invocation.rst | 9 +++++++++ sphinx/make_mode.py | 7 ++++--- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index a71059dca..1fa361e03 100644 --- a/CHANGES +++ b/CHANGES @@ -5,6 +5,7 @@ Features added -------------- * #3241: emit latex warning if buggy titlesec (ref #3210) +* #3194: Refer the $MAKE environment variable to determine ``make`` command Bugs fixed ---------- diff --git a/doc/invocation.rst b/doc/invocation.rst index a16ab2128..18c6d5035 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -384,6 +384,15 @@ You can also give one or more filenames on the command line after the source and build directories. Sphinx will then try to build only these output files (and their dependencies). +Environment variables +--------------------- + +The :program:`sphinx-build` refers following environment variables: + +.. desribe:: MAKE + + A path to make command. A command name is also allowed. + :program:`sphinx-build` uses it to invoke sub-build process on make-mode. Makefile options ---------------- diff --git a/sphinx/make_mode.py b/sphinx/make_mode.py index 28316458e..6aeeab802 100644 --- a/sphinx/make_mode.py +++ b/sphinx/make_mode.py @@ -62,6 +62,7 @@ class Make(object): self.srcdir = srcdir self.builddir = builddir self.opts = opts + self.makecmd = os.environ.get('MAKE', 'make') # refer $MAKE to determine make command def builddir_join(self, *comps): return path.join(self.builddir, *comps) @@ -162,13 +163,13 @@ class Make(object): if self.run_generic_build('latex') > 0: return 1 with cd(self.builddir_join('latex')): - os.system('make all-pdf') + os.system('%s all-pdf' % self.makecmd) def build_latexpdfja(self): if self.run_generic_build('latex') > 0: return 1 with cd(self.builddir_join('latex')): - os.system('make all-pdf-ja') + os.system('%s all-pdf-ja' % self.makecmd) def build_text(self): if self.run_generic_build('text') > 0: @@ -189,7 +190,7 @@ class Make(object): if self.run_generic_build('texinfo') > 0: return 1 with cd(self.builddir_join('texinfo')): - os.system('make info') + os.system('%s info' % self.makecmd) def build_gettext(self): dtdir = self.builddir_join('gettext', '.doctrees') From 9fc53cecf74fae33ac8509d34eea334ad4193d2b Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 15 Dec 2016 13:12:13 +0900 Subject: [PATCH 2/9] Reduce deprecation warnings (refs: #3192) --- sphinx/ext/autodoc.py | 5 ++++- tests/path.py | 3 ++- tests/run.py | 5 +++++ tests/test_directive_code.py | 16 +++++++--------- tests/test_ext_graphviz.py | 2 +- tests/test_intl.py | 15 +++++++-------- tests/util.py | 8 ++++++++ 7 files changed, 34 insertions(+), 20 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index c17b754e7..c3832bfda 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -15,6 +15,7 @@ import re import sys import inspect import traceback +import warnings from types import FunctionType, BuiltinFunctionType, MethodType from six import PY2, iterkeys, iteritems, itervalues, text_type, class_types, \ @@ -544,7 +545,9 @@ class Documenter(object): for modname in self.env.config.autodoc_mock_imports: dbg('[autodoc] adding a mock module %s!', modname) mock_import(modname) - __import__(self.modname) + with warnings.catch_warnings(): + warnings.filterwarnings("ignore", category=ImportWarning) + __import__(self.modname) parent = None obj = self.module = sys.modules[self.modname] dbg('[autodoc] => %r', obj) diff --git a/tests/path.py b/tests/path.py index 959b54875..ef1f35004 100755 --- a/tests/path.py +++ b/tests/path.py @@ -142,7 +142,8 @@ class path(text_type): """ Returns the text in the file. """ - with open(self, mode='U', encoding=encoding, **kwargs) as f: + mode = 'rU' if PY2 else 'r' + with open(self, mode=mode, encoding=encoding, **kwargs) as f: text = f.read() contents = repr_as(text, '<%s contents>' % self.basename()) return contents diff --git a/tests/run.py b/tests/run.py index d2d3b9fc8..273b2ee6b 100755 --- a/tests/run.py +++ b/tests/run.py @@ -13,6 +13,7 @@ from __future__ import print_function import os import sys +import warnings import traceback from path import path @@ -48,4 +49,8 @@ tempdir.makedirs() print('Running Sphinx test suite (with Python %s)...' % sys.version.split()[0]) sys.stdout.flush() +# filter warnings of test dependencies +warnings.filterwarnings('ignore', category=DeprecationWarning, module='nose.util') +warnings.filterwarnings('ignore', category=DeprecationWarning, module='site') # virtualenv + nose.main(argv=sys.argv) diff --git a/tests/test_directive_code.py b/tests/test_directive_code.py index 8f926956e..cb6221355 100644 --- a/tests/test_directive_code.py +++ b/tests/test_directive_code.py @@ -9,15 +9,13 @@ :license: BSD, see LICENSE for details. """ -from xml.etree import ElementTree - -from util import with_app +from util import with_app, etree_parse @with_app('xml', testroot='directive-code') def test_code_block(app, status, warning): app.builder.build('index') - et = ElementTree.parse(app.outdir / 'index.xml') + et = etree_parse(app.outdir / 'index.xml') secs = et.findall('./section/section') code_block = secs[0].findall('literal_block') assert len(code_block) > 0 @@ -33,7 +31,7 @@ def test_code_block(app, status, warning): @with_app('xml', testroot='directive-code') def test_code_block_dedent(app, status, warning): app.builder.build(['dedent_code']) - et = ElementTree.parse(app.outdir / 'dedent_code.xml') + et = etree_parse(app.outdir / 'dedent_code.xml') blocks = et.findall('./section/section/literal_block') for i in range(5): # 0-4 @@ -94,7 +92,7 @@ def test_code_block_namedlink_latex(app, status, warning): @with_app('xml', testroot='directive-code') def test_literal_include(app, status, warning): app.builder.build(['index']) - et = ElementTree.parse(app.outdir / 'index.xml') + et = etree_parse(app.outdir / 'index.xml') secs = et.findall('./section/section') literal_include = secs[1].findall('literal_block') literal_src = (app.srcdir / 'literal.inc').text(encoding='utf-8') @@ -109,7 +107,7 @@ def test_literal_include_dedent(app, status, warning): literal_lines = [l[4:] for l in literal_src.split('\n')[9:11]] app.builder.build(['dedent']) - et = ElementTree.parse(app.outdir / 'dedent.xml') + et = etree_parse(app.outdir / 'dedent.xml') blocks = et.findall('./section/section/literal_block') for i in range(5): # 0-4 @@ -124,7 +122,7 @@ def test_literal_include_dedent(app, status, warning): @with_app('xml', testroot='directive-code') def test_literal_include_block_start_with_comment_or_brank(app, status, warning): app.builder.build(['python']) - et = ElementTree.parse(app.outdir / 'python.xml') + et = etree_parse(app.outdir / 'python.xml') secs = et.findall('./section/section') literal_include = secs[0].findall('literal_block') assert len(literal_include) > 0 @@ -290,7 +288,7 @@ def test_literalinclude_namedlink_latex(app, status, warning): @with_app('xml', testroot='directive-code') def test_literalinclude_classes(app, status, warning): app.builder.build(['classes']) - et = ElementTree.parse(app.outdir / 'classes.xml') + et = etree_parse(app.outdir / 'classes.xml') secs = et.findall('./section/section') code_block = secs[0].findall('literal_block') diff --git a/tests/test_ext_graphviz.py b/tests/test_ext_graphviz.py index aa97f4135..7d464343f 100644 --- a/tests/test_ext_graphviz.py +++ b/tests/test_ext_graphviz.py @@ -26,7 +26,7 @@ def skip_if_graphviz_not_found(fn): dot = subprocess.Popen([graphviz_dot, '-V'], stdout=subprocess.PIPE, stderr=subprocess.PIPE) # show version - dot.wait() + dot.communicate() found = True except OSError: # No such file or directory pass diff --git a/tests/test_intl.py b/tests/test_intl.py index 4a517c111..21d6f763b 100644 --- a/tests/test_intl.py +++ b/tests/test_intl.py @@ -16,7 +16,6 @@ import re import pickle from docutils import nodes from subprocess import Popen, PIPE -from xml.etree import ElementTree from babel.messages import pofile from nose.tools import assert_equal @@ -24,7 +23,7 @@ from six import string_types from util import tempdir, rootdir, path, gen_with_app, with_app, SkipTest, \ assert_re_search, assert_not_re_search, assert_in, assert_not_in, \ - assert_startswith, assert_node, repr_as + assert_startswith, assert_node, repr_as, etree_parse root = tempdir / 'test-intl' @@ -502,7 +501,7 @@ def test_xml_builder(app, status, warning): # --- footnotes: regression test for fix #955, #1176 - et = ElementTree.parse(app.outdir / 'footnote.xml') + et = etree_parse(app.outdir / 'footnote.xml') secs = et.findall('section') para0 = secs[0].findall('paragraph') @@ -542,7 +541,7 @@ def test_xml_builder(app, status, warning): # --- footnote backlinks: i18n test for #1058 - et = ElementTree.parse(app.outdir / 'footnote.xml') + et = etree_parse(app.outdir / 'footnote.xml') secs = et.findall('section') para0 = secs[0].findall('paragraph') @@ -558,7 +557,7 @@ def test_xml_builder(app, status, warning): # --- refs in the Python domain - et = ElementTree.parse(app.outdir / 'refs_python_domain.xml') + et = etree_parse(app.outdir / 'refs_python_domain.xml') secs = et.findall('section') # regression test for fix #1363 @@ -570,7 +569,7 @@ def test_xml_builder(app, status, warning): # --- keep external links: regression test for #1044 - et = ElementTree.parse(app.outdir / 'external_links.xml') + et = etree_parse(app.outdir / 'external_links.xml') secs = et.findall('section') para0 = secs[0].findall('paragraph') @@ -623,7 +622,7 @@ def test_xml_builder(app, status, warning): # --- role xref: regression test for #1090, #1193 - et = ElementTree.parse(app.outdir / 'role_xref.xml') + et = etree_parse(app.outdir / 'role_xref.xml') sec1, sec2 = et.findall('section') para1, = sec1.findall('paragraph') @@ -674,7 +673,7 @@ def test_xml_builder(app, status, warning): # --- label targets: regression test for #1193, #1265 - et = ElementTree.parse(app.outdir / 'label_target.xml') + et = etree_parse(app.outdir / 'label_target.xml') secs = et.findall('section') para0 = secs[0].findall('paragraph') diff --git a/tests/util.py b/tests/util.py index 120492d47..13366a1da 100644 --- a/tests/util.py +++ b/tests/util.py @@ -11,7 +11,9 @@ import os import re import sys import tempfile +import warnings from functools import wraps +from xml.etree import ElementTree from six import StringIO, string_types @@ -155,6 +157,12 @@ def skip_unless_importable(module, msg=None): return skip_if(False, msg) +def etree_parse(path): + with warnings.catch_warnings(record=False): + warnings.filterwarnings("ignore", category=DeprecationWarning) + return ElementTree.parse(path) + + class Struct(object): def __init__(self, **kwds): self.__dict__.update(kwds) From 921182c37bfd9777213b24130ff3e2f753e30503 Mon Sep 17 00:00:00 2001 From: jfbu Date: Thu, 15 Dec 2016 10:15:42 +0100 Subject: [PATCH 3/9] Close #3210: emit latex warning if buggy titlesec. Simplify #3241, no need for ``\AtBeginDocument`` wrapper. --- sphinx/texinputs/sphinx.sty | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index eb2febbb0..f57283c19 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -18,11 +18,11 @@ \RequirePackage{amstext} \RequirePackage{textcomp} \RequirePackage{titlesec} -\AtBeginDocument{\@ifpackagelater{titlesec}{2016/03/15}% - {\@ifpackagelater{titlesec}{2016/03/21}{}% - {\AtEndDocument{\PackageWarningNoLine{sphinx}{^^J% +\@ifpackagelater{titlesec}{2016/03/15}% + {\@ifpackagelater{titlesec}{2016/03/21}{}% + {\AtEndDocument{\PackageWarningNoLine{sphinx}{^^J% ******** ERROR !! PLEASE UPDATE titlesec.sty !!********^^J% -******** THIS VERSION SWALLOWS SECTION NUMBERS.********}}}}{}} +******** THIS VERSION SWALLOWS SECTION NUMBERS.********}}}}{} \RequirePackage{tabulary} \RequirePackage{makeidx} % For framing code-blocks and warning type notices, and shadowing topics From 732bb213ca66bc2e0134d99f4469da4b1840b661 Mon Sep 17 00:00:00 2001 From: shimizukawa Date: Thu, 15 Dec 2016 21:53:13 +0900 Subject: [PATCH 4/9] add link to Changes in toppage --- doc/_templates/index.html | 36 +++++++++++++++++++++----------- doc/_templates/indexsidebar.html | 4 ++-- 2 files changed, 26 insertions(+), 14 deletions(-) diff --git a/doc/_templates/index.html b/doc/_templates/index.html index 755a79122..b4bdb5985 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -46,18 +46,30 @@

{%trans%}Documentation{%endtrans%}

- - +
-

{%trans%}First steps with Sphinx{%endtrans%}
- {%trans%}overview of basic tasks{%endtrans%}

-

{%trans%}Contents{%endtrans%}
- {%trans%}for a complete overview{%endtrans%}

- 		- {%- if hasdoc('search') %}

{%trans%}Search page{%endtrans%}
- {%trans%}search the documentation{%endtrans%}

{%- endif %} - {%- if hasdoc('genindex') %}

{%trans%}General Index{%endtrans%}
- {%trans%}all functions, classes, terms{%endtrans%}

{%- endif %} -
+ + + + + + +
+

{%trans%}First steps with Sphinx{%endtrans%}
+ {%trans%}overview of basic tasks{%endtrans%}

+ 		+ {%- if hasdoc('search') %}

{%trans%}Search page{%endtrans%}
+ {%trans%}search the documentation{%endtrans%}

{%- endif %} +
+

{%trans%}Contents{%endtrans%}
+ {%trans%}for a complete overview{%endtrans%}

+ 		+ {%- if hasdoc('genindex') %}

{%trans%}General Index{%endtrans%}
+ {%trans%}all functions, classes, terms{%endtrans%}

{%- endif %} +
+

{%trans%}Changes{%endtrans%}
+ {%trans%}release history{%endtrans%}

+ 		+

{%trans%} diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index b6f12f031..bfa0139cb 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -4,14 +4,14 @@

Download

{% if version.endswith('a0') %} -

{%trans%}This documentation is for version {{ version }}, which is +

{%trans%}This documentation is for version {{ version }}, which is not released yet.{%endtrans%}

{%trans%}You can use it from the Git repo or look for released versions in the Python Package Index.{%endtrans%}

{% else %} -

{%trans%}Current version: {{ version }}{%endtrans%}

+

{%trans%}Current version: {{ version }}{%endtrans%}

{%trans%}Get Sphinx from the Python Package Index, or install it with:{%endtrans%}

pip install -U Sphinx
From cf795894b9290c5ab2035ae21535f0a7f4b7107a Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Fri, 16 Dec 2016 19:44:27 +0900 Subject: [PATCH 5/9] Fix #3246: xapian search adapter crashes --- CHANGES | 2 ++ sphinx/websupport/search/xapiansearch.py | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index 1fa361e03..ad85d2ca0 100644 --- a/CHANGES +++ b/CHANGES @@ -10,6 +10,8 @@ Features added Bugs fixed ---------- +* #3246: xapian search adapter crashes + Release 1.5.1 (released Dec 13, 2016) ===================================== diff --git a/sphinx/websupport/search/xapiansearch.py b/sphinx/websupport/search/xapiansearch.py index 1e43dcbe9..aa7cff86a 100644 --- a/sphinx/websupport/search/xapiansearch.py +++ b/sphinx/websupport/search/xapiansearch.py @@ -39,16 +39,16 @@ class XapianSearch(BaseSearch): # Ensure the db lock is removed. del self.database - def add_document(self, path, title, text): + def add_document(self, pagename, filename, title, text): self.database.begin_transaction() # sphinx_page_path is used to easily retrieve documents by path. - sphinx_page_path = '"sphinxpagepath%s"' % path.replace('/', '_') + sphinx_page_path = '"sphinxpagepath%s"' % pagename.replace('/', '_') # Delete the old document if it exists. self.database.delete_document(sphinx_page_path) doc = xapian.Document() doc.set_data(text) - doc.add_value(self.DOC_PATH, path) + doc.add_value(self.DOC_PATH, pagename) doc.add_value(self.DOC_TITLE, title) self.indexer.set_document(doc) self.indexer.index_text(text) From a82aebcd7d418cfffae1984f5a62c2f488f60132 Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Fri, 16 Dec 2016 16:52:11 +0100 Subject: [PATCH 6/9] Add CONTRIBUTING file --- CONTRIBUTING.rst | 331 ++++++++++++++++++++++++++++++++++++++++++++++ doc/devguide.rst | 332 +---------------------------------------------- 2 files changed, 332 insertions(+), 331 deletions(-) create mode 100644 CONTRIBUTING.rst mode change 100644 => 120000 doc/devguide.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 000000000..f29646550 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,331 @@ +Sphinx Developer's Guide +======================== + +.. topic:: Abstract + + This document describes the development process of Sphinx, a documentation + system used by developers to document systems used by other developers to + develop other systems that may also be documented using Sphinx. + +The Sphinx source code is managed using Git and is hosted on Github. + + git clone git://github.com/sphinx-doc/sphinx + +.. rubric:: Community + +sphinx-users + Mailing list for user support. + +sphinx-dev + Mailing list for development related discussions. + +#sphinx-doc on irc.freenode.net + IRC channel for development questions and user support. + + +Bug Reports and Feature Requests +-------------------------------- + +If you have encountered a problem with Sphinx or have an idea for a new +feature, please submit it to the `issue tracker`_ on Github or discuss it +on the sphinx-dev mailing list. + +For bug reports, please include the output produced during the build process +and also the log file Sphinx creates after it encounters an un-handled +exception. The location of this file should be shown towards the end of the +error message. + +Including or providing a link to the source files involved may help us fix the +issue. If possible, try to create a minimal project that produces the error +and post that instead. + +.. _`issue tracker`: https://github.com/sphinx-doc/sphinx/issues + + +Contributing to Sphinx +---------------------- + +The recommended way for new contributors to submit code to Sphinx is to fork +the repository on Github and then submit a pull request after +committing the changes. The pull request will then need to be approved by one +of the core developers before it is merged into the main repository. + +#. Check for open issues or open a fresh issue to start a discussion around a + feature idea or a bug. +#. If you feel uncomfortable or uncertain about an issue or your changes, feel + free to email sphinx-dev@googlegroups.com. +#. Fork `the repository`_ on Github to start making your changes to the + **master** branch for next major version, or **stable** branch for next + minor version. +#. Write a test which shows that the bug was fixed or that the feature works + as expected. +#. Send a pull request and bug the maintainer until it gets merged and + published. Make sure to add yourself to AUTHORS_ and the change to + CHANGES_. + +.. _`the repository`: https://github.com/sphinx-doc/sphinx +.. _AUTHORS: https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS +.. _CHANGES: https://github.com/sphinx-doc/sphinx/blob/master/CHANGES + + +Getting Started +~~~~~~~~~~~~~~~ + +These are the basic steps needed to start developing on Sphinx. + +#. Create an account on Github. + +#. Fork the main Sphinx repository (`sphinx-doc/sphinx + `_) using the Github interface. + +#. Clone the forked repository to your machine. :: + + git clone https://github.com/USERNAME/sphinx + cd sphinx + +#. Checkout the appropriate branch. + + For changes that should be included in the next minor release (namely bug + fixes), use the ``stable`` branch. :: + + git checkout stable + + For new features or other substantial changes that should wait until the + next major release, use the ``master`` branch. + +#. Optional: setup a virtual environment. :: + + virtualenv ~/sphinxenv + . ~/sphinxenv/bin/activate + pip install -e . + +#. Create a new working branch. Choose any name you like. :: + + git checkout -b feature-xyz + +#. Hack, hack, hack. + + For tips on working with the code, see the `Coding Guide`_. + +#. Test, test, test. Possible steps: + + * Run the unit tests:: + + pip install -r test-reqs.txt + make test + + * Again, it's useful to turn on deprecation warnings on so they're shown in + the test output:: + + PYTHONWARNINGS=all make test + + * Build the documentation and check the output for different builders:: + + cd doc + make clean html latexpdf + + * Run the unit tests under different Python environments using + :program:`tox`:: + + pip install tox + tox -v + + * Add a new unit test in the ``tests`` directory if you can. + + * For bug fixes, first add a test that fails without your changes and passes + after they are applied. + + * Tests that need a sphinx-build run should be integrated in one of the + existing test modules if possible. New tests that to ``@with_app`` and + then ``build_all`` for a few assertions are not good since *the test suite + should not take more than a minute to run*. + +#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not + trivial (small doc updates, typo fixes). Then commit:: + + git commit -m '#42: Add useful new feature that does this.' + + Github recognizes certain phrases that can be used to automatically + update the issue tracker. + + For example:: + + git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.' + + would close issue #42. + +#. Push changes in the branch to your forked repository on Github. :: + + git push origin feature-xyz + +#. Submit a pull request from your branch to the respective branch (``master`` + or ``stable``) on ``sphinx-doc/sphinx`` using the Github interface. + +#. Wait for a core developer to review your changes. + + +Core Developers +~~~~~~~~~~~~~~~ + +The core developers of Sphinx have write access to the main repository. They +can commit changes, accept/reject pull requests, and manage items on the issue +tracker. + +You do not need to be a core developer or have write access to be involved in +the development of Sphinx. You can submit patches or create pull requests +from forked repositories and have a core developer add the changes for you. + +The following are some general guidelines for core developers: + +* Questionable or extensive changes should be submitted as a pull request + instead of being committed directly to the main repository. The pull + request should be reviewed by another core developer before it is merged. + +* Trivial changes can be committed directly but be sure to keep the repository + in a good working state and that all tests pass before pushing your changes. + +* When committing code written by someone else, please attribute the original + author in the commit message and any relevant :file:`CHANGES` entry. + + +Locale updates +~~~~~~~~~~~~~~ + +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``: + +* Use ``python setup.py extract_messages`` to update the ``.pot`` template. +* Use ``python setup.py update_catalog`` to update all existing language + catalogs in ``sphinx/locale/*/LC_MESSAGES`` with the current messages in the + template file. +* Use ``python setup.py compile_catalog`` to compile the ``.po`` files to binary + ``.mo`` files and ``.js`` files. + +When an updated ``.po`` file is submitted, run compile_catalog to commit both +the source and the compiled catalogs. + +When a new locale is submitted, add a new directory with the ISO 639-1 language +identifier and put ``sphinx.po`` in there. Don't forget to update the possible +values for :confval:`language` in ``doc/config.rst``. + +The Sphinx core messages can also be translated on `Transifex +`_. There exists a client tool named ``tx`` in the +Python package "transifex_client", which can be used to pull translations in +``.po`` format from Transifex. To do this, go to ``sphinx/locale`` and then run +``tx pull -f -l LANG`` where LANG is an existing language identifier. It is +good practice to run ``python setup.py update_catalog`` afterwards to make sure +the ``.po`` file has the canonical Babel formatting. + + +Coding Guide +------------ + +* Try to use the same code style as used in the rest of the project. See the + `Pocoo Styleguide`__ for more information. + + __ http://flask.pocoo.org/docs/styleguide/ + +* For non-trivial changes, please update the :file:`CHANGES` file. If your + changes alter existing behavior, please document this. + +* New features should be documented. Include examples and use cases where + appropriate. If possible, include a sample that is displayed in the + generated output. + +* When adding a new configuration variable, be sure to document it and update + :file:`sphinx/quickstart.py` if it's important enough. + +* Use the included :program:`utils/check_sources.py` script to check for + common formatting issues (trailing whitespace, lengthy lines, etc). + +* Add appropriate unit tests. + + +Debugging Tips +~~~~~~~~~~~~~~ + +* Delete the build cache before building documents if you make changes in the + code by running the command ``make clean`` or using the + :option:`sphinx-build -E` option. + +* Use the :option:`sphinx-build -P` option to run Pdb on exceptions. + +* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable + representation of the document structure. + +* Set the configuration variable :confval:`keep_warnings` to ``True`` so + warnings will be displayed in the generated output. + +* Set the configuration variable :confval:`nitpicky` to ``True`` so that Sphinx + will complain about references without a known target. + +* Set the debugging options in the `Docutils configuration file + `_. + +* JavaScript stemming algorithms in `sphinx/search/*.py` (except `en.py`) are + generated by this + `modified snowballcode generator `_. + Generated `JSX `_ files are + in `this repository `_. + You can get the resulting JavaScript files using the following command: + + .. code-block:: bash + + $ npm install + $ node_modules/.bin/grunt build # -> dest/*.global.js + +Deprecating a feature +--------------------- + +There are a couple reasons that code in Sphinx might be deprecated: + +* If a feature has been improved or modified in a backwards-incompatible way, + the old feature or behavior will be deprecated. + +* Sometimes Sphinx will include a backport of a Python library that's not + included in a version of Python that Sphinx currently supports. When Sphinx + no longer needs to support the older version of Python that doesn't include + the library, the library will be deprecated in Sphinx. + +As the :ref:`deprecation-policy` describes, +the first release of Sphinx that deprecates a feature (``A.B``) should raise a +``RemovedInSphinxXXWarning`` (where XX is the Sphinx version where the feature +will be removed) when the deprecated feature is invoked. Assuming we have good +test coverage, these warnings are converted to errors when running the test +suite with warnings enabled: ``python -Wall tests/run.py``. Thus, when adding +a ``RemovedInSphinxXXWarning`` you need to eliminate or silence any warnings +generated when running the tests. + +.. _deprecation-policy: + +Deprecation policy +------------------ + +A feature release may deprecate certain features from previous releases. If a +feature is deprecated in feature release 1.A, it will continue to work in all +1.A.x versions (for all versions of x) but raise warnings. Deprecated features +will be removed in the first 1.B release, or 1.B.1 for features deprecated in +the last 1.A.x feature release to ensure deprecations are done over at least 2 +feature releases. + +So, for example, if we decided to start the deprecation of a function in +Sphinx 1.4: + +* Sphinx 1.4.x will contain a backwards-compatible replica of the function + which will raise a ``RemovedInSphinx16Warning``. + +* Sphinx 1.5 (the version that follows 1.4) will still contain the + backwards-compatible replica. + +* Sphinx 1.6 will remove the feature outright. + +The warnings are displayed by default. You can turn off display of these +warnings with: + +* ``PYTHONWARNINGS= make html`` (Linux/Mac) +* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac) +* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows) diff --git a/doc/devguide.rst b/doc/devguide.rst deleted file mode 100644 index f29646550..000000000 --- a/doc/devguide.rst +++ /dev/null @@ -1,331 +0,0 @@ -Sphinx Developer's Guide -======================== - -.. topic:: Abstract - - This document describes the development process of Sphinx, a documentation - system used by developers to document systems used by other developers to - develop other systems that may also be documented using Sphinx. - -The Sphinx source code is managed using Git and is hosted on Github. - - git clone git://github.com/sphinx-doc/sphinx - -.. rubric:: Community - -sphinx-users - Mailing list for user support. - -sphinx-dev - Mailing list for development related discussions. - -#sphinx-doc on irc.freenode.net - IRC channel for development questions and user support. - - -Bug Reports and Feature Requests --------------------------------- - -If you have encountered a problem with Sphinx or have an idea for a new -feature, please submit it to the `issue tracker`_ on Github or discuss it -on the sphinx-dev mailing list. - -For bug reports, please include the output produced during the build process -and also the log file Sphinx creates after it encounters an un-handled -exception. The location of this file should be shown towards the end of the -error message. - -Including or providing a link to the source files involved may help us fix the -issue. If possible, try to create a minimal project that produces the error -and post that instead. - -.. _`issue tracker`: https://github.com/sphinx-doc/sphinx/issues - - -Contributing to Sphinx ----------------------- - -The recommended way for new contributors to submit code to Sphinx is to fork -the repository on Github and then submit a pull request after -committing the changes. The pull request will then need to be approved by one -of the core developers before it is merged into the main repository. - -#. Check for open issues or open a fresh issue to start a discussion around a - feature idea or a bug. -#. If you feel uncomfortable or uncertain about an issue or your changes, feel - free to email sphinx-dev@googlegroups.com. -#. Fork `the repository`_ on Github to start making your changes to the - **master** branch for next major version, or **stable** branch for next - minor version. -#. Write a test which shows that the bug was fixed or that the feature works - as expected. -#. Send a pull request and bug the maintainer until it gets merged and - published. Make sure to add yourself to AUTHORS_ and the change to - CHANGES_. - -.. _`the repository`: https://github.com/sphinx-doc/sphinx -.. _AUTHORS: https://github.com/sphinx-doc/sphinx/blob/master/AUTHORS -.. _CHANGES: https://github.com/sphinx-doc/sphinx/blob/master/CHANGES - - -Getting Started -~~~~~~~~~~~~~~~ - -These are the basic steps needed to start developing on Sphinx. - -#. Create an account on Github. - -#. Fork the main Sphinx repository (`sphinx-doc/sphinx - `_) using the Github interface. - -#. Clone the forked repository to your machine. :: - - git clone https://github.com/USERNAME/sphinx - cd sphinx - -#. Checkout the appropriate branch. - - For changes that should be included in the next minor release (namely bug - fixes), use the ``stable`` branch. :: - - git checkout stable - - For new features or other substantial changes that should wait until the - next major release, use the ``master`` branch. - -#. Optional: setup a virtual environment. :: - - virtualenv ~/sphinxenv - . ~/sphinxenv/bin/activate - pip install -e . - -#. Create a new working branch. Choose any name you like. :: - - git checkout -b feature-xyz - -#. Hack, hack, hack. - - For tips on working with the code, see the `Coding Guide`_. - -#. Test, test, test. Possible steps: - - * Run the unit tests:: - - pip install -r test-reqs.txt - make test - - * Again, it's useful to turn on deprecation warnings on so they're shown in - the test output:: - - PYTHONWARNINGS=all make test - - * Build the documentation and check the output for different builders:: - - cd doc - make clean html latexpdf - - * Run the unit tests under different Python environments using - :program:`tox`:: - - pip install tox - tox -v - - * Add a new unit test in the ``tests`` directory if you can. - - * For bug fixes, first add a test that fails without your changes and passes - after they are applied. - - * Tests that need a sphinx-build run should be integrated in one of the - existing test modules if possible. New tests that to ``@with_app`` and - then ``build_all`` for a few assertions are not good since *the test suite - should not take more than a minute to run*. - -#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not - trivial (small doc updates, typo fixes). Then commit:: - - git commit -m '#42: Add useful new feature that does this.' - - Github recognizes certain phrases that can be used to automatically - update the issue tracker. - - For example:: - - git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.' - - would close issue #42. - -#. Push changes in the branch to your forked repository on Github. :: - - git push origin feature-xyz - -#. Submit a pull request from your branch to the respective branch (``master`` - or ``stable``) on ``sphinx-doc/sphinx`` using the Github interface. - -#. Wait for a core developer to review your changes. - - -Core Developers -~~~~~~~~~~~~~~~ - -The core developers of Sphinx have write access to the main repository. They -can commit changes, accept/reject pull requests, and manage items on the issue -tracker. - -You do not need to be a core developer or have write access to be involved in -the development of Sphinx. You can submit patches or create pull requests -from forked repositories and have a core developer add the changes for you. - -The following are some general guidelines for core developers: - -* Questionable or extensive changes should be submitted as a pull request - instead of being committed directly to the main repository. The pull - request should be reviewed by another core developer before it is merged. - -* Trivial changes can be committed directly but be sure to keep the repository - in a good working state and that all tests pass before pushing your changes. - -* When committing code written by someone else, please attribute the original - author in the commit message and any relevant :file:`CHANGES` entry. - - -Locale updates -~~~~~~~~~~~~~~ - -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``: - -* Use ``python setup.py extract_messages`` to update the ``.pot`` template. -* Use ``python setup.py update_catalog`` to update all existing language - catalogs in ``sphinx/locale/*/LC_MESSAGES`` with the current messages in the - template file. -* Use ``python setup.py compile_catalog`` to compile the ``.po`` files to binary - ``.mo`` files and ``.js`` files. - -When an updated ``.po`` file is submitted, run compile_catalog to commit both -the source and the compiled catalogs. - -When a new locale is submitted, add a new directory with the ISO 639-1 language -identifier and put ``sphinx.po`` in there. Don't forget to update the possible -values for :confval:`language` in ``doc/config.rst``. - -The Sphinx core messages can also be translated on `Transifex -`_. There exists a client tool named ``tx`` in the -Python package "transifex_client", which can be used to pull translations in -``.po`` format from Transifex. To do this, go to ``sphinx/locale`` and then run -``tx pull -f -l LANG`` where LANG is an existing language identifier. It is -good practice to run ``python setup.py update_catalog`` afterwards to make sure -the ``.po`` file has the canonical Babel formatting. - - -Coding Guide ------------- - -* Try to use the same code style as used in the rest of the project. See the - `Pocoo Styleguide`__ for more information. - - __ http://flask.pocoo.org/docs/styleguide/ - -* For non-trivial changes, please update the :file:`CHANGES` file. If your - changes alter existing behavior, please document this. - -* New features should be documented. Include examples and use cases where - appropriate. If possible, include a sample that is displayed in the - generated output. - -* When adding a new configuration variable, be sure to document it and update - :file:`sphinx/quickstart.py` if it's important enough. - -* Use the included :program:`utils/check_sources.py` script to check for - common formatting issues (trailing whitespace, lengthy lines, etc). - -* Add appropriate unit tests. - - -Debugging Tips -~~~~~~~~~~~~~~ - -* Delete the build cache before building documents if you make changes in the - code by running the command ``make clean`` or using the - :option:`sphinx-build -E` option. - -* Use the :option:`sphinx-build -P` option to run Pdb on exceptions. - -* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable - representation of the document structure. - -* Set the configuration variable :confval:`keep_warnings` to ``True`` so - warnings will be displayed in the generated output. - -* Set the configuration variable :confval:`nitpicky` to ``True`` so that Sphinx - will complain about references without a known target. - -* Set the debugging options in the `Docutils configuration file - `_. - -* JavaScript stemming algorithms in `sphinx/search/*.py` (except `en.py`) are - generated by this - `modified snowballcode generator `_. - Generated `JSX `_ files are - in `this repository `_. - You can get the resulting JavaScript files using the following command: - - .. code-block:: bash - - $ npm install - $ node_modules/.bin/grunt build # -> dest/*.global.js - -Deprecating a feature ---------------------- - -There are a couple reasons that code in Sphinx might be deprecated: - -* If a feature has been improved or modified in a backwards-incompatible way, - the old feature or behavior will be deprecated. - -* Sometimes Sphinx will include a backport of a Python library that's not - included in a version of Python that Sphinx currently supports. When Sphinx - no longer needs to support the older version of Python that doesn't include - the library, the library will be deprecated in Sphinx. - -As the :ref:`deprecation-policy` describes, -the first release of Sphinx that deprecates a feature (``A.B``) should raise a -``RemovedInSphinxXXWarning`` (where XX is the Sphinx version where the feature -will be removed) when the deprecated feature is invoked. Assuming we have good -test coverage, these warnings are converted to errors when running the test -suite with warnings enabled: ``python -Wall tests/run.py``. Thus, when adding -a ``RemovedInSphinxXXWarning`` you need to eliminate or silence any warnings -generated when running the tests. - -.. _deprecation-policy: - -Deprecation policy ------------------- - -A feature release may deprecate certain features from previous releases. If a -feature is deprecated in feature release 1.A, it will continue to work in all -1.A.x versions (for all versions of x) but raise warnings. Deprecated features -will be removed in the first 1.B release, or 1.B.1 for features deprecated in -the last 1.A.x feature release to ensure deprecations are done over at least 2 -feature releases. - -So, for example, if we decided to start the deprecation of a function in -Sphinx 1.4: - -* Sphinx 1.4.x will contain a backwards-compatible replica of the function - which will raise a ``RemovedInSphinx16Warning``. - -* Sphinx 1.5 (the version that follows 1.4) will still contain the - backwards-compatible replica. - -* Sphinx 1.6 will remove the feature outright. - -The warnings are displayed by default. You can turn off display of these -warnings with: - -* ``PYTHONWARNINGS= make html`` (Linux/Mac) -* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac) -* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows) diff --git a/doc/devguide.rst b/doc/devguide.rst new file mode 120000 index 000000000..798f2aa2f --- /dev/null +++ b/doc/devguide.rst @@ -0,0 +1 @@ +../CONTRIBUTING.rst \ No newline at end of file From 3b9d83e15e8708c446952c4d14bef2a4bcd80595 Mon Sep 17 00:00:00 2001 From: jfbu Date: Fri, 16 Dec 2016 18:20:16 +0100 Subject: [PATCH 7/9] Fix typo (ref #3243). --- doc/invocation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/invocation.rst b/doc/invocation.rst index 18c6d5035..d65fa27c4 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -389,7 +389,7 @@ Environment variables The :program:`sphinx-build` refers following environment variables: -.. desribe:: MAKE +.. describe:: MAKE A path to make command. A command name is also allowed. :program:`sphinx-build` uses it to invoke sub-build process on make-mode. From 1ccfb9736bebbf5453d62c5ad3bc7e946d11f67d Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 17 Dec 2016 14:46:39 +0900 Subject: [PATCH 8/9] doc: Add a note for var, ivar and cvar --- doc/domains.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/domains.rst b/doc/domains.rst index 7ff0d2f5f..43395eac3 100644 --- a/doc/domains.rst +++ b/doc/domains.rst @@ -318,6 +318,11 @@ are recognized and formatted nicely: * ``returns``, ``return``: Description of the return value. * ``rtype``: Return type. Creates a link if possible. +.. note:: + + In current release, all ``var``, ``ivar`` and ``cvar`` are represented as "Variable". + There is no difference at all. + The field names must consist of one of these keywords and an argument (except for ``returns`` and ``rtype``, which do not need an argument). This is best explained by an example:: From 93dacedfed5f5a4d39b9e2a5a054e6aedddf88d8 Mon Sep 17 00:00:00 2001 From: shimizukawa Date: Sat, 17 Dec 2016 15:38:56 +0900 Subject: [PATCH 9/9] Fix #3253: In Py2 environment, building another locale with a non-captioned toctree produces `None` captions --- CHANGES | 2 ++ sphinx/addnodes.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index ad85d2ca0..07771f0ef 100644 --- a/CHANGES +++ b/CHANGES @@ -11,6 +11,8 @@ Bugs fixed ---------- * #3246: xapian search adapter crashes +* #3253: In Py2 environment, building another locale with a non-captioned + toctree produces `None` captions Release 1.5.1 (released Dec 13, 2016) ===================================== diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index 95f58052d..b85637c87 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -49,7 +49,7 @@ class toctree(nodes.General, nodes.Element, translatable): """Node for inserting a "TOC tree".""" def preserve_original_messages(self): - if 'caption' in self: + if self.get('caption'): self['rawcaption'] = self['caption'] def apply_translated_message(self, original_message, translated_message):