# conf.py
language='en'
html_extra_path = ["customize.html"]
<!-- customize.html -->
{{ variables }} <!-- from the conf.py -->
{{ language }} <!-- expected output: en -->
如何让customize.html知道变量来自配置？
.. note ::假定custom.html文件不在主题的文档中。
我可以用Jinja自己做，但这不是我想要的。
我认为sphinx已经提供了一种处理方法，有人知道吗？
我破解了代码（即，您无法直接使用sphinx-build.exe构建）来实现它。
首先，我们观察sphinx-build.exe做的事情。
# site-packages\Sphinx-x.x.x.dist-info\entry_points.txt
[console_scripts]
...
sphinx-build = sphinx.cmd.build:main
...
然后您知道它实际上调用了sphinx.cmd.build:main来运行，您可以参考它并进行修改以使您满意。
例如：
import sphinx.cmd.build
from sphinx.application import Sphinx
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.cmd.build import patch_docutils, docutils_namespace, handle_exception, Sphinx
def setup_extra_html(app):
html_builder = app.builder
ctx = {attr: app.config[attr] for attr in dir(app.config) if not attr.startswith('_')}
html_builder.globalcontext = ctx.copy()
# Please put your HTML to the ``templates_path`` that you define, since it concept about the BuiltinTemplateLoader.pathchain
pagename = 'disqus_statistic' # <-- your HTML, you can set it on the conf.py and then get it with ``ctx``
templatename = f'{pagename}.html'
html_builder.handle_page(pagename=pagename, addctx=dict(), templatename=templatename, outfilename=None)
def your_build_main(*args):
...
try:
with patch_docutils(source_dir)), docutils_namespace():
app = Sphinx(...)
if isinstance(app.builder, StandaloneHTMLBuilder):
setup_extra_html(app)
app.build(force_all=False, filenames)
return app.statuscode
except (Exception, KeyboardInterrupt) as exc:
...
cmd_list = [source_dir, output_dir, '-b', 'html', ...]
sphinx.cmd.build.build_main = your_build_main # override it.
sphinx.cmd.build.main(cmd_list) # it will call sphinx.cmd.build.build_main
现在，以下内容将按预期工作。
<!-- original disqus_statistic.html -->
{%- if html_favicon %}
<a href="{{ pathto(html_favicon, 1) }}">Test Icon</a>
{%- endif %}
{{ language }}
由于代码太长，您应该自己完成细节。或者您可以参考我的sphinx_cmd_build.py
脚本tl; dr
# your_extension.py
from sphinx.application import Sphinx
from sphinx.builders.html import StandaloneHTMLBuilder
import pathlib
def expand_init_builder(app):
Sphinx._init_builder(app)
do_something(app)
def setup(app: Sphinx):
app.add_config_value('config_value_define_by_you', default='', rebuild=True)
app._init_builder = lambda: expand_init_builder(app)
def do_something(app: Sphinx):
user_config = {attr: app.config[attr] for attr in dir(app.config) if not attr.startswith('_')} # all variable of conf.py
# user_config.update(...) # Hard coding is fine, but not recommend.
user_config.update(dict(Path=pathlib.Path)) # recommend you, it's useful.
html_builder: StandaloneHTMLBuilder = app.builder
html_builder.globalcontext = user_config
html_builder.handle_page(pagename=page_name, addctx=dict(), templatename=template_name, outfilename=None)
# conf.py
# sys.path.insert(...)
extensions.append('your_extension') # Make sure your scrips can found in sys.path.
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-templates_path
templates_path = ['_templates/sphinx_rtd_theme'] # I hope you know what I mean... see the above link.
# I put my_html.html in ``_templates/sphinx_rtd_theme/my_html.html``
config_value_define_by_you = "https://github.com/CarsonSlovoka/typing-game"
<!-- my_html.html -->
{{ Path(config_value_define_by_you).name }} <!-- render result: typing-game -->
Sphinx-build.exe在做什么？
app = Sphinx(...)StandaloneHTMLBuilder然后，您知道构建器创建的所有文件。这个想法是：如果我们可以获取构建者，那么我们可以做任何我们想做的事情。
您将找到在Sphinx(...)之后创建的构建器，所以解决方法之一，我在setup_extra_html
app = Sphinx(...)如果您不喜欢编写这些代码并认为它太复杂。
第二种方法是编写扩展名，概念与上述相同-尝试获取构建器
您看到Sphinx(...)其构造函数，并找到如下代码
class Sphinx:
def __init__(...):
...
# load all user-given extension modules
for extension in self.config.extensions:
self.setup_extension(extension) # <-- the extension you write
...
# create the builder
self.builder = self.create_builder(buildername) <-- this is we want
self._init_env(freshenv)
self._init_builder()
然后，您知道了创建扩展程序的常规方法，而这些扩展程序无法获得构建器，但是您会注意到，如果在self._init_builder（）完成之后执行某些操作，那么就可以了。
我提供我的项目供您参考。我真正想要的是，我想创建一个页面，希望它可以计算每篇文章的评论数量并向我展示。您将了解，如果我不使用狮身人面像，而是选择命名约定，那么我必须对很多事情进行硬编码。
希望您能获得帮助，并认为它有用！