IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch '3.x' into 7293_js_splitter_code

Browse Source
This commit is contained in:
Takeshi KOMIYA
2020-03-17 10:48:44 +09:00
committed by GitHub
parent 28b3360863 ba99fae8a0
commit 4086760f6b
16 changed files with 105 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.codecov.yml
View File

@@ -4,3 +4,6 @@ coverage:
project:
default:
enabled: no
patch:
default:
enabled: no

5
CHANGES
View File

@@ -28,6 +28,8 @@ Incompatible changes
* #6903: Internal data structure of C, Python, reST and standard domains have
changed. The node_id is added to the index of objects and modules. Now they
contains a pair of docname and node_id for cross reference.
* #7276: C++ domain: Non intended behavior is removed such as ``say_hello_``
links to ``.. cpp:function:: say_hello()``
* #7210: js domain: Non intended behavior is removed such as ``parseInt_`` links
to ``.. js:function:: parseInt``
* #7229: rst domain: Non intended behavior is removed such as ``numref_`` links
@@ -63,6 +65,7 @@ Features added
* #2815: autodoc: Support singledispatch functions and methods
* #7079: autodoc: :confval:`autodoc_typehints` accepts ``"description"``
configuration. It shows typehints as object description
* #7314: apidoc: Propagate ``--maxdepth`` option through package documents
* #6558: glossary: emit a warning for duplicated glossary entry
* #3106: domain: Register hyperlink target for index page automatically
* #6558: std domain: emit a warning for duplicated generic objects
@@ -88,6 +91,8 @@ Features added
using ``:nosearch:`` file-wide metadata
* #7293: html search: Allow to override JavaScript splitter via
``SearchLanguage.js_splitter_code``
* #7142: html theme: Add a theme option: ``pygments_dark_style`` to switch the
style of code-blocks in dark mode
Bugs fixed
----------

19
CONTRIBUTING.rst
View File

@@ -387,18 +387,31 @@ Sphinx 2.x:
* Sphinx 2.x will contain a backwards-compatible replica of the function
which will raise a ``RemovedInSphinx40Warning``.
This is a subclass of :exc:`python:PendingDeprecationWarning`, i.e. it
will not get displayed by default.
* Sphinx 3.x will still contain the backwards-compatible replica.
* Sphinx 3.x will still contain the backwards-compatible replica, but
``RemovedInSphinx40Warning`` will be a subclass of
:exc:`python:DeprecationWarning` then, and gets displayed by default.
* Sphinx 4.0 will remove the feature outright.
The warnings are displayed by default. You can turn off display of these
warnings with:
Deprecation warnings
~~~~~~~~~~~~~~~~~~~~
Sphinx will enable its ``RemovedInNextVersionWarning`` warnings by default,
if :envvar:`python:PYTHONWARNINGS` is not set.
Therefore you can disable them using:
* ``PYTHONWARNINGS= make html`` (Linux/Mac)
* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
But you can also explicitly enable the pending ones using e.g.
``PYTHONWARNINGS=default`` (see the
:ref:`Python docs on configuring warnings <python:describing-warning-filters>`)
for more details.
Unit Testing
------------

3
doc/development/tutorials/examples/todo.py
View File

@@ -70,6 +70,9 @@ def process_todo_nodes(app, doctree, fromdocname):
# Augment each todo with a backlink to the original location.
env = app.builder.env
if not hasattr(env, 'todo_all_todos'):
env.todo_all_todos = []
for node in doctree.traverse(todolist):
if not app.config.todo_include_todos:
node.replace_self([])

2
doc/man/sphinx-autogen.rst
View File

@@ -73,7 +73,7 @@ If you run the following:
.. code-block:: bash
$ PYTHONPATH=. sphinx-autodoc doc/index.rst
$ PYTHONPATH=. sphinx-autogen docs/index.rst
then the following stub files will be created in ``docs``::

5
doc/theming.rst
View File

@@ -63,6 +63,11 @@ Python :mod:`ConfigParser` module) and has the following structure:
highlighting. This can be overridden by the user in the
:confval:`pygments_style` config value.
* The **pygments_dark_style** setting gives the name of a Pygments style to use
for highlighting when the CSS media query ``(prefers-color-scheme: dark)``
evaluates to true. It is injected into the page using
:meth:`~Sphinx.add_css_file()`.
* The **sidebars** setting gives the comma separated list of sidebar templates
for constructing sidebars. This can be overridden by the user in the
:confval:`html_sidebars` config value.

19
sphinx/builders/html/__init__.py
View File

@@ -271,6 +271,19 @@ class StandaloneHTMLBuilder(Builder):
style = 'sphinx'
self.highlighter = PygmentsBridge('html', style)
if self.theme:
dark_style = self.theme.get_config('theme', 'pygments_dark_style', None)
else:
dark_style = None
if dark_style is not None:
self.dark_highlighter = PygmentsBridge('html', dark_style)
self.add_css_file('pygments_dark.css',
media='(prefers-color-scheme: dark)',
id='pygments_dark_css')
else:
self.dark_highlighter = None
def init_css_files(self) -> None:
for filename, attrs in self.app.registry.css_files:
self.add_css_file(filename, **attrs)
@@ -484,7 +497,7 @@ class StandaloneHTMLBuilder(Builder):
'parents': [],
'logo': logo,
'favicon': favicon,
'html5_doctype': html5_ready and not self.config.html4_writer
'html5_doctype': html5_ready and not self.config.html4_writer,
}
if self.theme:
self.globalcontext.update(
@@ -719,6 +732,10 @@ class StandaloneHTMLBuilder(Builder):
with open(path.join(self.outdir, '_static', 'pygments.css'), 'w') as f:
f.write(self.highlighter.get_stylesheet())
if self.dark_highlighter:
with open(path.join(self.outdir, '_static', 'pygments_dark.css'), 'w') as f:
f.write(self.dark_highlighter.get_stylesheet())
def copy_translation_js(self) -> None:
"""Copy a JavaScript file for translations."""
if self.config.language is not None:

10
sphinx/domains/cpp.py
View File

@@ -5371,9 +5371,13 @@ class DefinitionParser:
prevErrors.append((e, "If type argument"))
self.pos = pos
try:
# actually here we shouldn't use the fallback parser (hence allow=False),
# because if actually took the < in an expression, then we _will_ fail,
# which is handled elsewhere. E.g., :cpp:expr:`A <= 0`.
def parser():
return self._parse_constant_expression(inTemplate=True)
value = self._parse_expression_fallback([',', '>'], parser)
value = self._parse_expression_fallback(
[',', '>'], parser, allow=False)
self.skip_ws()
if self.skip_string('>'):
parsedEnd = True
@@ -6512,10 +6516,6 @@ class CPPObject(ObjectDescription):
names = self.env.domaindata['cpp']['names']
if name not in names:
names[name] = ast.symbol.docname
signode['names'].append(name)
else:
# print("[CPP] non-unique name:", name)
pass
# always add the newest id
assert newestId
signode['ids'].append(newestId)

2
sphinx/domains/std.py
View File

@@ -62,7 +62,7 @@ class GenericObject(ObjectDescription):
signode.clear()
signode += addnodes.desc_name(sig, sig)
# normalize whitespace like XRefRole does
name = ws_re.sub('', sig)
name = ws_re.sub(' ', sig)
return name
def add_target_and_index(self, name: str, sig: str, signode: desc_signature) -> None:

1
sphinx/ext/apidoc.py
View File

@@ -175,6 +175,7 @@ def create_package_file(root: str, master_package: str, subroot: str, py_files:
'separatemodules': opts.separatemodules,
'automodule_options': options,
'show_headings': not opts.noheadings,
'maxdepth': opts.maxdepth,
}
text = ReSTRenderer([user_template_dir, template_dir]).render('package.rst_t', context)
write_file(pkgname, text, opts)

1
sphinx/templates/apidoc/package.rst_t
View File

@@ -7,6 +7,7 @@
{%- macro toctree(docnames) -%}
.. toctree::
:maxdepth: {{ maxdepth }}
{% for docname in docnames %}
{{ docname }}
{%- endfor %}

1
tests/roots/test-theming/test_theme/test-theme/theme.conf
View File

@@ -1,3 +1,4 @@
[theme]
inherit = classic
sidebars = globaltoc.html, searchbox.html
pygments_dark_style = monokai

5
tests/test_build_html.py
View File

@@ -1526,6 +1526,11 @@ def test_html_pygments_for_classic_theme(app):
assert style.__name__ == 'SphinxStyle'
@pytest.mark.sphinx('html', testroot='basic')
def test_html_dark_pygments_style_default(app):
assert app.builder.dark_highlighter is None
@pytest.mark.sphinx(testroot='basic', srcdir='validate_html_extra_path')
def test_validate_html_extra_path(app):
(app.confdir / '_static').makedirs()

17
tests/test_domain_cpp.py
View File

@@ -110,6 +110,20 @@ def test_expressions():
if id4 is not None:
idDict[4] = ids % id4
check('class', 'template<> C<a[%s]>' % expr, idDict)
class Config:
cpp_id_attributes = ["id_attr"]
cpp_paren_attributes = ["paren_attr"]
parser = DefinitionParser(expr, None, Config())
parser.allowFallbackExpressionParsing = False
ast = parser.parse_expression()
res = str(ast)
if res != expr:
print("")
print("Input: ", expr)
print("Result: ", res)
raise DefinitionError("")
# primary
exprCheck('nullptr', 'LDnE')
exprCheck('true', 'L1E')
@@ -214,11 +228,14 @@ def test_expressions():
exprCheck('5 != 42', 'neL5EL42E')
# ['<=', '>=', '<', '>']
exprCheck('5 <= 42', 'leL5EL42E')
exprCheck('A <= 42', 'le1AL42E')
exprCheck('5 >= 42', 'geL5EL42E')
exprCheck('5 < 42', 'ltL5EL42E')
exprCheck('A < 42', 'lt1AL42E')
exprCheck('5 > 42', 'gtL5EL42E')
# ['<<', '>>']
exprCheck('5 << 42', 'lsL5EL42E')
exprCheck('A << 42', 'ls1AL42E')
exprCheck('5 >> 42', 'rsL5EL42E')
# ['+', '-']
exprCheck('5 + 42', 'plL5EL42E')

9
tests/test_ext_apidoc.py
View File

@@ -121,15 +121,16 @@ def test_pep_0420_enabled_separate(make_app, apidoc):
with open(outdir / 'a.b.c.rst') as f:
rst = f.read()
assert ".. toctree::\n\n a.b.c.d\n" in rst
assert ".. toctree::\n :maxdepth: 4\n\n a.b.c.d\n" in rst
with open(outdir / 'a.b.e.rst') as f:
rst = f.read()
assert ".. toctree::\n\n a.b.e.f\n" in rst
assert ".. toctree::\n :maxdepth: 4\n\n a.b.e.f\n" in rst
with open(outdir / 'a.b.x.rst') as f:
rst = f.read()
assert ".. toctree::\n\n a.b.x.y\n" in rst
assert ".. toctree::\n :maxdepth: 4\n\n a.b.x.y\n" in rst
app = make_app('text', srcdir=outdir)
app.build()
@@ -485,6 +486,7 @@ def test_package_file(tempdir):
"-----------\n"
"\n"
".. toctree::\n"
" :maxdepth: 4\n"
"\n"
" testpkg.subpkg\n"
"\n"
@@ -546,6 +548,7 @@ def test_package_file_separate(tempdir):
"----------\n"
"\n"
".. toctree::\n"
" :maxdepth: 4\n"
"\n"
" testpkg.example\n"
"\n"

18
tests/test_theming.py
View File

@@ -11,8 +11,8 @@
import os
import alabaster
import pytest
import pytest
from sphinx.theming import ThemeError
@@ -117,6 +117,22 @@ def test_staticfiles(app, status, warning):
assert '<meta name="testopt" content="optdefault" />' in result
@pytest.mark.sphinx(testroot='theming',
confoverrides={'html_theme': 'test-theme'})
def test_dark_style(app, status, warning):
style = app.builder.dark_highlighter.formatter_args.get('style')
assert style.__name__ == 'MonokaiStyle'
app.build()
assert (app.outdir / '_static' / 'pygments_dark.css').exists()
result = (app.outdir / 'index.html').read_text()
assert '<link rel="stylesheet" href="_static/pygments.css" type="text/css" />' in result
assert ('<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" '
'rel="stylesheet" type="text/css" '
'href="_static/pygments_dark.css" />') in result
@pytest.mark.sphinx(testroot='theming')
def test_theme_sidebars(app, status, warning):
app.build()