0.4

spacemanspiff2007 · spacemanspiff2007 · commit 262df2913a36 · 2022-03-09T06:46:19.000+01:00
diff --git a/.github/workflows/run_tox.yml b/.github/workflows/run_tox.yml
@@ -8,7 +8,7 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: [3.7, 3.8, 3.9]
+        python-version: ['3.7', '3.8', '3.9', '3.10']
 
     steps:
     - uses: actions/checkout@v1
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,13 +1,13 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.4.0
+    rev: v4.1.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
       - id: trailing-whitespace
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.8.0
+    rev: 5.10.1
     hooks:
       - id: isort
         name: isort (python)
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -18,7 +18,7 @@ formats: all
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3.8
+  version: 3.9
   install:
     - requirements: requirements.txt
     - method: setuptools
diff --git a/doc/configuration.rst b/doc/configuration.rst
@@ -10,6 +10,8 @@ To use this extension just add it to the ``extensions`` in your ``conf.py``
 
 Additionally the following configuration parameters are available:
 
+.. _config_options:
+
 .. list-table::
    :widths: auto
    :header-rows: 1
@@ -20,13 +22,18 @@ Additionally the following configuration parameters are available:
 
    * - ``exec_code_working_dir``
      - ``Path`` or ``str``
-     - The working directory where the code will be executed
+     - The working directory where the code will be executed.
 
    * - ``exec_code_folders``
      - | ``List`` of
        | ``Path`` or ``str``
      - | Additional folders that will be added to PYTHONPATH.
-       | Use this to e.g. make imports available
+       | Use this to e.g. make imports available.
+
+   * - ``exec_code_example_dir``
+     - ``Path`` or ``str``
+     - | The directory that is used to create the path to the
+       | example files. Defaults to the parent folder of the ``conf.py``.
 
 If it's a relative path it will be resolved relative to the parent folder of the ``conf.py``
 
@@ -36,6 +43,7 @@ Example:
 
    exec_code_working_dir = '..'
    exec_code_folders = ['../my_src']
+   exec_code_example_dir = '.'
 
 If you are unsure what the values are you can run Sphinx build in verbose mode with ``-v -v``.
 The configured values are logged.
@@ -46,3 +54,4 @@ Log output for Example:
 
    [exec-code] Working dir: C:\Python\sphinx-exec-code
    [exec-code] Folders: C:\Python\sphinx-exec-code\my_src
+   [exec-code] Example dir: C:\Python\sphinx-exec-code\doc
diff --git a/doc/description.rst b/doc/description.rst
@@ -60,6 +60,27 @@ Generated view
 
 ----
 
+Code from files
+------------------------------
+It's possible to have code in example files with the ``filename`` option.
+The folder that is used to resolve to a file name can be :ref:`configured <config_options>`.
+
+Example:
+
+.. code-block:: python
+
+   .. exec_code::
+      :filename: file_example.py
+
+
+Generated view
+
+----
+
+.. exec_code::
+   :filename: file_example.py
+
+----
 
 Code Markers
 ------------------------------
diff --git a/doc/file_example.py b/doc/file_example.py
@@ -0,0 +1 @@
+print('This is code from an example file')
diff --git a/readme.md b/readme.md
@@ -36,6 +36,9 @@ This code will be executed
 ```
 
 # Changelog
+#### 0.4 (09.03.2022)
+- Added option to run code from example files
+
 #### 0.3 (24.09.2021)
 - Added some more documentation and fixed some false path warnings
 
diff --git a/requirements.txt b/requirements.txt
@@ -1,4 +1,4 @@
-pytest==6.2.5
-pre-commit==2.15.0
-sphinx==4.2.0
+pytest==7.0.1
+pre-commit==2.17.0
+sphinx==4.4.0
 sphinx-rtd-theme==1.0.0
diff --git a/setup.py b/setup.py
@@ -55,6 +55,7 @@ def load_version() -> str:
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3 :: Only",
     ],
 )
diff --git a/src/sphinx_exec_code/__version__.py b/src/sphinx_exec_code/__version__.py
@@ -1 +1 @@
-__version__ = '0.3'
+__version__ = '0.4'
diff --git a/src/sphinx_exec_code/sphinx_api.py b/src/sphinx_exec_code/sphinx_api.py
@@ -3,10 +3,11 @@
 from sphinx_exec_code import __version__
 from sphinx_exec_code.__const__ import log
 from sphinx_exec_code.code_exec import setup_code_env
-from sphinx_exec_code.sphinx_exec import ExecCode
+from sphinx_exec_code.sphinx_exec import ExecCode, setup_example_dir
 
 CONF_NAME_CWD = 'exec_code_working_dir'
 CONF_NAME_DIRS = 'exec_code_folders'
+CONF_NAME_SAMPLE_DIR = 'exec_code_example_dir'
 
 
 def mk_path(app, obj) -> Path:
@@ -18,15 +19,19 @@ def mk_path(app, obj) -> Path:
 
 
 def builder_ready(app):
-    cwd = mk_path(app, app.config.exec_code_working_dir)
-    folders = tuple(mk_path(app, _p) for _p in app.config.exec_code_folders)
+    cwd = mk_path(app, getattr(app.config, CONF_NAME_CWD))
+    folders = tuple(mk_path(app, _p) for _p in getattr(app.config, CONF_NAME_DIRS))
+    example_dir = mk_path(app, getattr(app.config, CONF_NAME_SAMPLE_DIR))
 
     log.debug(f'[exec-code] Working dir: {cwd}')
     log.debug(f'[exec-code] Folders: {", ".join(map(str, folders))}')
+    log.debug(f'[exec-code] Example dir: {example_dir}')
 
     # Ensure dirs are valid
     if not cwd.is_dir():
         raise FileNotFoundError(f'Working directory "{cwd}" not found! (configured by {CONF_NAME_CWD})')
+    if not example_dir.is_dir():
+        raise FileNotFoundError(f'Example directory "{example_dir}" not found! (configured by {CONF_NAME_SAMPLE_DIR})')
     for _f in folders:
         if not _f.is_dir():
             raise FileNotFoundError(f'Additional directory "{_f}" not found! (configured by {CONF_NAME_DIRS})')
@@ -50,6 +55,7 @@ def builder_ready(app):
         if not package_found:
             log.warning(f'[exec-code] No Python packages found in {_f}')
 
+    setup_example_dir(example_dir)
     setup_code_env(cwd, folders)
     return None
 
@@ -69,6 +75,7 @@ def setup(app):
     # config options
     app.add_config_value(CONF_NAME_CWD, cwd, 'env',)
     app.add_config_value(CONF_NAME_DIRS, code_folders, 'env')
+    app.add_config_value(CONF_NAME_SAMPLE_DIR, confdir, 'env')
 
     app.connect('builder-inited', builder_ready)
     app.add_directive('exec_code', ExecCode)
diff --git a/src/sphinx_exec_code/sphinx_exec.py b/src/sphinx_exec_code/sphinx_exec.py
@@ -1,4 +1,6 @@
 import traceback
+from pathlib import Path
+from typing import Optional
 
 from docutils import nodes
 from sphinx.errors import ExtensionError
@@ -9,6 +11,13 @@
 from sphinx_exec_code.code_format import get_show_exec_code, VisibilityMarkerError
 from sphinx_exec_code.sphinx_spec import build_spec, SpecCode, SpecOutput, SphinxSpecBase
 
+EXAMPLE_DIR: Optional[Path] = None
+
+
+def setup_example_dir(example_dir: Path):
+    global EXAMPLE_DIR
+    EXAMPLE_DIR = example_dir
+
 
 def create_literal_block(objs: list, code: str, spec: SphinxSpecBase):
     if spec.hide or not code:
@@ -58,15 +67,23 @@ def _run(self) -> list:
         """
         output = []
         file, line = self.get_source_info()
+        content = self.content
+
+        code_spec = SpecCode.from_options(self.options)
+
+        # Read from example files
+        if code_spec.filename:
+            filename = (EXAMPLE_DIR / code_spec.filename).resolve()
+            content = filename.read_text(encoding='utf-8').splitlines()
 
         # format the code
         try:
-            code_show, code_exec = get_show_exec_code(self.content)
+            code_show, code_exec = get_show_exec_code(content)
         except Exception as e:
             raise ExtensionError(f'Could not parse code markers at {self.get_location()}', orig_exc=e)
 
         # Show the code from the user
-        create_literal_block(output, code_show, spec=SpecCode.from_options(self.options))
+        create_literal_block(output, code_show, spec=code_spec)
 
         try:
             code_results = execute_code(code_exec, file, line)
diff --git a/src/sphinx_exec_code/sphinx_spec.py b/src/sphinx_exec_code/sphinx_spec.py
@@ -50,12 +50,18 @@ class SpecCode(SphinxSpecBase):
         'caption': 'caption',
         'language': 'language',
         'linenos': 'linenos',
+        'filename': 'filename',
     }
     defaults = {
         'caption': '',
         'language': 'python',
+        'filename': '',
     }
 
+    def __init__(self, hide: bool, linenos: bool, caption: str, language: str, filename: str):
+        super().__init__(hide, linenos, caption, language)
+        self.filename: str = filename
+
 
 class SpecOutput(SphinxSpecBase):
     aliases = {
diff --git a/tests/test_sphinx_spec.py b/tests/test_sphinx_spec.py
@@ -7,9 +7,7 @@
 from sphinx_exec_code.sphinx_spec import build_spec, SpecCode, SpecOutput, SphinxSpecBase
 
 
-def test_aliases():
-    assert list(SpecCode.aliases.values()) == list(SpecOutput.aliases.values())
-
+def test_aliases_unique():
     for key_code in SpecCode.aliases:
         assert key_code not in SpecOutput.aliases
     for key_output in SpecOutput.aliases:
@@ -23,7 +21,7 @@ def test_default_in_aliases(cls: Type[SphinxSpecBase]):
         assert k in names
 
 
-def test_build_spec():
+def test_build_spec_code():
     spec = build_spec()
 
     for name in chain(SpecCode.aliases.keys(), SpecOutput.aliases.keys()):
@@ -34,6 +32,7 @@ def test_build_spec():
         'linenos': directives.flag,
         'caption': directives.unchanged,
         'language': directives.unchanged,
+        'filename': directives.unchanged,
 
         'hide_output': directives.flag,
         'linenos_output': directives.flag,
@@ -48,6 +47,7 @@ def test_spec_code():
     assert obj.language == 'python'
     assert obj.linenos is True
     assert obj.hide is False
+    assert obj.filename == ''
 
 
 def test_spec_output():
diff --git a/tox.ini b/tox.ini
@@ -4,14 +4,16 @@ envlist =
     py37
     py38
     py39
+    py310
     flake
     docs
 
 [gh-actions]
 python =
     3.7: py37
-    3.8: py38, flake, docs
-    3.9: py39
+    3.8: py38
+    3.9: py39, flake, docs
+    3.10: py310
 
 [testenv]
 deps =

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+print('This is code from an example file')`
Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,7 @@ def load_version() -> str:`
`55`	`55`	`"Programming Language :: Python :: 3.7",`
`56`	`56`	`"Programming Language :: Python :: 3.8",`
`57`	`57`	`"Programming Language :: Python :: 3.9",`
	`58`	`+ "Programming Language :: Python :: 3.10",`
`58`	`59`	`"Programming Language :: Python :: 3 :: Only",`
`59`	`60`	`],`
`60`	`61`	`)`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-__version__ = '0.3'`
	`1`	`+__version__ = '0.4'`