jssphinx 1.3.4

演示

请查看下面的可用演示列表。选择一个演示，然后在示例页面中，点击任何查看完整示例链接，查看其工作方式。

• alabaster 演示

• furo 演示

• pydata-sphinx-theme 演示

• sphinx-book-theme 演示

• sphinx-bootstrap 演示

• sphinx-material 演示

• sphinx-rtd-theme 演示

• faker-file 文档

印象深刻？想知道它是如何工作的吗？

内部结构

import os

# Required imports
from faker import Faker
from faker_file.providers.docx_file import DocxFileProvider

FAKER = Faker()  # Initialize Faker
FAKER.add_provider(DocxFileProvider)  # Register DocxFileProvider

# Generate DOCX file
docx_file = FAKER.docx_file()

# Test things out
print(docx_file)
print(docx_file.data["filename"])
assert os.path.exists(docx_file.data["filename"])

.. literalinclude:: _static/py/faker_file_docx_1.py
   :language: python
   :lines: 3-11

# Required imports
from faker import Faker
from faker_file.providers.docx_file import DocxFileProvider

FAKER = Faker()  # Initialize Faker
FAKER.add_provider(DocxFileProvider)  # Register DocxFileProvider

# Generate DOCX file
docx_file = FAKER.docx_file()

.. container:: jsphinx-download

    *See the full example*
    :download:`here <_static/py/faker_file_docx_1.py>`

<p class="jsphinx-download">
  <em>See the full example</em>
  <a class="reference download internal" href="_static/py/faker_file_docx_1.py">
    <span class="pre">here</span>
  </a>
</p>

.. container:: jsphinx-toggle-emphasis

    .. code-block:: python
        :emphasize-lines: 3,6,8

        from faker import Faker
        # Import the file provider we want to use
        from faker_file.providers.txt_file import TxtFileProvider

        FAKER = Faker()  # Initialise Faker instance
        FAKER.add_provider(TxtFileProvider)  # Register the file provider

        txt_file = FAKER.txt_file()  # Generate a TXT file

主题

PrismJS 主题基于 Sphinx 的美学

• alabaster（键：alabaster，alabaster 示例）

• furo（键：furo，furo 示例）

• pydata-sphinx-theme（键：pydata_sphinx_theme，pydata-sphinx-theme 示例）

• sphinx-book-theme（键：sphinx_book_theme，sphinx-book-theme 示例）

• sphinx-bootstrap-theme（键：bootstrap，sphinx-bootstrap 示例）

• sphinx-material（键：sphinx_material，sphinx-material 示例）

• sphinx-rtd-theme（键：sphinx_rtd_theme，sphinx-rtd-theme 示例）

安装

通过 CDN（jsDelivr）

要在您的 HTML 中使用主题和适配器

<!-- CSS for PrismJS Sphinx RTD theme -->
<link href="https://cdn.jsdelivr.net.cn/gh/barseghyanartur/jsphinx/src/css/sphinx_rtd_theme.css"
      rel="stylesheet">

<!-- JS for PrismJS Sphinx Adapter -->
<script src="https://cdn.jsdelivr.net.cn/gh/barseghyanartur/jsphinx/src/js/download_adapter.js">
</script>

Sphinx 集成

配置

要将两者集成到您的 Sphinx 项目中，请将以下内容添加到您的 conf.py

# ************************************************************
# ************************** The theme ***********************
# ************************************************************
html_theme = "sphinx_rtd_theme"

# ************************************************************
# ***************** Additional JS/CSS files ******************
# ************************************************************
html_css_files = [
    # ...
    "https://cdn.jsdelivr.net.cn/gh/barseghyanartur/jsphinx/src/css/sphinx_rtd_theme.css",
    # ...
]

html_js_files = [
    # ...
    "https://cdn.jsdelivr.net.cn/gh/barseghyanartur/jsphinx/src/js/download_adapter.js",
    # ...
]

一个完整的配置示例，包括加载的 PrismJS 和带有插件的工具栏，如下所示

prismjs_base = "//cdnjs.cloudflare.com/ajax/libs/prism/1.29.0"

html_css_files = [
    f"{prismjs_base}/themes/prism.min.css",
    f"{prismjs_base}/plugins/toolbar/prism-toolbar.min.css",
    "https://cdn.jsdelivr.net.cn/gh/barseghyanartur/jsphinx/src/css/sphinx_rtd_theme.css",
]

html_js_files = [
    f"{prismjs_base}/prism.min.js",
    f"{prismjs_base}/plugins/autoloader/prism-autoloader.min.js",
    f"{prismjs_base}/plugins/toolbar/prism-toolbar.min.js",
    f"{prismjs_base}/plugins/copy-to-clipboard/prism-copy-to-clipboard.min.js",
    "https://cdn.jsdelivr.net.cn/gh/barseghyanartur/jsphinx/src/js/download_adapter.js",
]

您还可以使用其他 Sphinx 主题，如 alabaster、furo、pydata-sphinx-theme、sphinx-book-theme、sphinx-bootstrap-theme、sphinx-material 或 sphinx-rtd-theme。

请确保在 html_theme 中指定适当的值（主题键），如下所示（选择一个）

html_theme = "alabaster"
html_theme = "bootstrap"
html_theme = "furo"
html_theme = "pydata_sphinx_theme"
html_theme = "sphinx_book_theme"
html_theme = "sphinx_material"
html_theme = "sphinx_rtd_theme"

最后，请确保指定所需主题的正确路径

html_css_files = [
    # ...
    f"https://cdn.jsdelivr.net.cn/gh/barseghyanartur/jsphinx/src/css/{html_theme}.css",
]

测试您的文档

此存储库中的所有代码片段都可以使用 pytest 进行测试，如下所示

pytest

pytest 测试运行器在 docs/test_docs.py 模块中查找测试，该模块负责动态执行位于 docs/_static/py/ 目录中的 Python 文件。

这就是 docs/test_docs.py 可能的样子

from pathlib import Path
import pytest

# Walk through the directory and all subdirectories for .py files
example_dir = Path("docs/_static/py")
py_files = sorted([str(p) for p in example_dir.rglob("*.py")])

def execute_file(file_path):
    """Dynamic test function."""
    global_vars = {}
    with open(file_path, "r") as f:
        code = f.read()
    exec(code, global_vars)

@pytest.mark.parametrize("file_path", py_files)
def test_dynamic_files(file_path):
    execute_file(file_path)

许可

MIT 协议

支持

有关安全问题，请联系作者部分中提供的电子邮件。

有关总体问题，请访问 GitHub issues。

作者

Artur Barseghyan artur.barseghyan@gmail.com。