-
Notifications
You must be signed in to change notification settings - Fork 2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add autosummary_filename_map config to avoid clashes #7927
Changes from 3 commits
72ca2bd
d401054
4e0ff5c
52c173b
71d1b37
aae8ce8
2b843dd
144f18a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
@@ -28,7 +28,7 @@ | |||||||||||||||
import warnings | ||||||||||||||||
from gettext import NullTranslations | ||||||||||||||||
from os import path | ||||||||||||||||
from typing import Any, Callable, Dict, List, NamedTuple, Set, Tuple, Union | ||||||||||||||||
from typing import Any, Callable, Dict, List, Mapping, NamedTuple, Set, Tuple, Union | ||||||||||||||||
|
||||||||||||||||
from jinja2 import TemplateNotFound | ||||||||||||||||
from jinja2.sandbox import SandboxedEnvironment | ||||||||||||||||
|
@@ -74,6 +74,7 @@ def __init__(self, translator: NullTranslations) -> None: | |||||||||||||||
self.warningiserror = False | ||||||||||||||||
|
||||||||||||||||
self.config.add('autosummary_context', {}, True, None) | ||||||||||||||||
self.config.add('autosummary_filename_map', {}, True, None) | ||||||||||||||||
tk0miya marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||
self.config.init_values() | ||||||||||||||||
|
||||||||||||||||
def emit_firstresult(self, *args: Any) -> None: | ||||||||||||||||
|
@@ -393,6 +394,14 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, | |||||||||||||||
# keep track of new files | ||||||||||||||||
new_files = [] | ||||||||||||||||
|
||||||||||||||||
if app: | ||||||||||||||||
filename_map = app.config.autosummary_filename_map | ||||||||||||||||
if not isinstance(filename_map, Mapping): | ||||||||||||||||
raise TypeError('autosummary_filename_map should be a mapping from ' | ||||||||||||||||
'strings to strings') | ||||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You don't need to check the value is dict here. The Sphinx automatically checks the given value is the same type as the default value. But it does not check the contents of the dict. I think the default check is enough. Note: If you'd like to add more careful validations, please use a hook for the config-inited event to validate user configurations. sphinx/sphinx/builders/latex/__init__.py Lines 498 to 503 in 98a854d
sphinx/sphinx/builders/latex/__init__.py Line 558 in 98a854d
|
||||||||||||||||
else: | ||||||||||||||||
filename_map = {} | ||||||||||||||||
|
||||||||||||||||
# write | ||||||||||||||||
for entry in sorted(set(items), key=str): | ||||||||||||||||
if entry.path is None: | ||||||||||||||||
|
@@ -418,7 +427,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, | |||||||||||||||
imported_members, app, entry.recursive, context, | ||||||||||||||||
modname, qualname) | ||||||||||||||||
|
||||||||||||||||
filename = os.path.join(path, name + suffix) | ||||||||||||||||
filename = os.path.join(path, filename_map.get(name, name) + suffix) | ||||||||||||||||
if os.path.isfile(filename): | ||||||||||||||||
with open(filename, encoding=encoding) as f: | ||||||||||||||||
old_content = f.read() | ||||||||||||||||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,31 +1,16 @@ | ||
Autosummary test | ||
tk0miya marked this conversation as resolved.
Show resolved
Hide resolved
|
||
================ | ||
sphinx | ||
====== | ||
|
||
.. autosummary:: | ||
:toctree: generated | ||
.. automodule:: sphinx | ||
|
||
sphinx.application.Sphinx | ||
|
||
|
||
|
||
|
||
.. currentmodule:: sphinx.application | ||
|
||
|
||
|
||
|
||
.. autoclass:: TemplateBridge | ||
|
||
Basic test | ||
|
||
.. autosummary:: | ||
|
||
render -- some ignored stuff goes here | ||
render_string More ignored stuff | ||
|
||
Test with tildes | ||
|
||
.. autosummary:: | ||
|
||
~TemplateBridge.render | ||
~TemplateBridge.render_string | ||
|
||
Methods: | ||
|
||
.. automethod:: render | ||
|
||
.. automethod:: render_string | ||
|
||
|
||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
from os import path # NOQA | ||
from typing import Union | ||
|
||
|
||
class Foo: | ||
class Bar: | ||
pass | ||
|
||
def __init__(self): | ||
pass | ||
|
||
def bar(self): | ||
pass | ||
|
||
@property | ||
def baz(self): | ||
pass | ||
|
||
|
||
class _Baz: | ||
pass | ||
|
||
|
||
def bar(x: Union[int, str], y: int = 1) -> None: | ||
pass | ||
|
||
|
||
def _quux(): | ||
pass | ||
|
||
|
||
class Exc(Exception): | ||
pass | ||
|
||
|
||
class _Exc(Exception): | ||
pass | ||
|
||
|
||
#: a module-level attribute | ||
qux = 2 | ||
tk0miya marked this conversation as resolved.
Show resolved
Hide resolved
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
import sys | ||
|
||
# Fail module import in a catastrophic way | ||
sys.exit(1) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
import os | ||
import sys | ||
|
||
sys.path.insert(0, os.path.abspath('.')) | ||
|
||
extensions = ['sphinx.ext.autosummary'] | ||
autosummary_generate = True | ||
|
||
# The suffix of source filenames. | ||
source_suffix = '.rst' | ||
tk0miya marked this conversation as resolved.
Show resolved
Hide resolved
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
|
||
:autolink:`autosummary_dummy_module.Foo` | ||
|
||
:autolink:`autosummary_importfail` | ||
tk0miya marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
.. autosummary:: | ||
:toctree: generated | ||
:caption: An autosummary | ||
|
||
autosummary_dummy_module | ||
autosummary_dummy_module.Foo | ||
autosummary_dummy_module.Foo.Bar | ||
autosummary_dummy_module.bar | ||
autosummary_dummy_module.qux | ||
autosummary_importfail | ||
tk0miya marked this conversation as resolved.
Show resolved
Hide resolved
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is better to add a new config variable alphabetically. Could you move this above?
(I noticed
autosummary_imported_members
is not. I'll fix it later)