0.0.1

.flake8

@@ -0,0 +1,24 @@
+[flake8]
+ignore =
+    # E201 whitespace after '('
+    E201,
+    # E221 multiple spaces before operator
+    E203,
+    # E203 whitespace before ':'
+    E221,
+    # E241 multiple spaces after ','
+    E241,
+    # E251 unexpected spaces around keyword / parameter equals
+    E251,
+    # E303 too many blank lines
+    E303,
+
+max-line-length = 120
+
+exclude =
+    __init__.py
+
+    .git,
+    .tox,
+
+    doc/conf.py

.github/workflows/publish-pypi.yml

@@ -0,0 +1,33 @@
+name: Publish Python distributions to PyPI
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-n-publish:
+    name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        ref: master
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+
+    - name: Install setuptools
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install --upgrade setuptools wheel twine
+
+    - name: Build a binary wheel and a source tarball
+      run: |
+        python setup.py sdist bdist_wheel
+
+    - name: Publish distribution to PyPI
+      uses: pypa/gh-action-pypi-publish@master
+      with:
+        user: __token__
+        password: ${{ secrets.pypi_api_key }}

.github/workflows/run_tox.yml

@@ -0,0 +1,24 @@
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 4
+      matrix:
+        python-version: [3.6, 3.7, 3.8, 3.9]
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install tox tox-gh-actions
+    - name: Test with tox
+      run: tox

.gitignore

@@ -127,3 +127,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# PyCharm
+/.idea

.isort.cfg

@@ -0,0 +1,10 @@
+[settings]
+line_length = 120
+
+src_paths=src, tests
+
+ensure_newline_before_comments = True
+force_alphabetical_sort_within_sections = True
+
+balanced_wrapping = True
+multi_line_output = 2

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.4.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.8.0
+    hooks:
+      - id: isort
+        name: isort (python)
+
+  - repo: https://gitlab.com/PyCQA/flake8
+    rev: '3.9.2'
+    hooks:
+    -   id: flake8

doc/conf.py

@@ -0,0 +1,61 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import logging
+import os
+import sys
+
+# required for sphinx_exec_code
+sys.path.insert(0, os.path.join(os.path.abspath('..'), 'src'))
+
+import sphinx_exec_code
+
+# -- Project information -----------------------------------------------------
+project = 'sphinx-exec-code'
+copyright = '2021, spacemanspiff2007'
+author = 'spacemanspiff2007'
+
+# The full version, including alpha/beta/rc tags
+release = sphinx_exec_code.__version__
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx_exec_code',
+]
+
+exec_code_working_dir = './src'
+exec_code_folders = ['./src']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

doc/configuration.rst

@@ -0,0 +1,46 @@
+Installation and Configuration
+==================================
+To use this extension just add it to the ``extensions`` in your ``conf.py``
+
+.. code-block::
+
+   extensions = [
+       'sphinx_exec_code',
+   ]
+
+Additionally the following configuration parameters are available:
+
+.. list-table::
+   :widths: auto
+   :header-rows: 1
+
+   * - Name
+     - Type
+     - Description
+
+   * - ``exec_code_working_dir``
+     - ``Path`` or ``str``
+     - 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
+
+Example:
+
+.. code-block::
+
+   exec_code_working_dir = '..'
+   exec_code_folders = ['./my_src']
+
+If you are unsure what the values are you can run Sphinx build in verbose mode with ``-v -v``.
+The configured values are logged.
+
+Log output for Example:
+
+::
+
+   [exec-code] Working dir: C:\Python\sphinx-exec-code
+   [exec-code] Folders: C:\Python\sphinx-exec-code\my_src

doc/description.rst

@@ -0,0 +1,101 @@
+
+Usage
+==================================
+
+Without options
+------------------------------
+.. code-block:: rst
+
+   .. exec_code::
+
+      print('Easy!')
+
+Generated view:
+
+.. exec_code::
+
+    print('Easy!')
+
+Options
+------------------------------
+It's possible to further configure both the code block and the output block with the following options:
+
+
+hide_code/hide_output:
+  Will hide the corresponding block
+caption/caption_output
+  Will add a caption above the block
+linenos/linenos_output
+  Will add line numbers
+language/language_output:
+  | Will add syntax highlighting for the specified language
+  | The default for the code block is python, the default for the output block is plain text
+
+
+Example:
+
+.. code-block:: rst
+
+   .. exec_code::
+      :linenos:
+      :hide_output:
+      :caption: This is an important caption
+
+      print('Easy!')
+
+Generated view:
+
+.. exec_code::
+  :linenos:
+  :hide_output:
+  :caption: This is an important caption
+
+  print('Easy!')
+
+
+Hide code parts
+------------------------------
+It's possible to hide parts of the code (e.g. to setup a working example)
+and it's possible to skip part of the code execution. This is possible with the
+``#hide:[start|stop|toggle]`` or ``#skip:[start|stop|toggle]`` marker in the code.
+
+Spaces and dashes are ignored for the case insensitive marker detection so these are all the same:
+
+.. code-block:: python
+
+   #HIDE:START
+   # hide: start
+   # ----- hide: start -----
+        # ----- hide: start -----
+
+
+Example:
+
+.. code-block:: rst
+
+   .. exec_code::
+
+      # --- hide: start ---
+      print('Setup!')
+      #hide:toggle
+      print('Easy!')
+      # --- hide: start ---
+      print('Hidden!')
+      # --- hide: stop ---
+      # Note the missing entries!
+      print('Visible!')
+
+
+Generated view:
+
+.. exec_code::
+
+   # --- hide: start ---
+   print('Setup!')
+   #hide:toggle
+   print('Easy!')
+   # --- hide: start ---
+   print('Hidden!')
+   # --- hide: stop ---
+   # Note the missing entries!
+   print('Visible!')

doc/index.rst

@@ -0,0 +1,19 @@
+:github_url: https://github.com/spacemanspiff2007/sphinx-exec-code
+
+Welcome to the sphinx-exec-code documentation!
+==============================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   configuration
+   description
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+addopts = -p no:cacheprovider

readme.md

@@ -0,0 +1,36 @@
+# sphinx-exec-code
+![Tests Status](https://github.com/spacemanspiff2007/sphinx-exec-code/workflows/Tests/badge.svg)
+[![Documentation Status](https://readthedocs.org/projects/sphinx-exec-code/badge/?version=latest)](https://sphinx-exec-code.readthedocs.io/en/latest/)
+[![Updates](https://pyup.io/repos/github/spacemanspiff2007/sphinx-exec-code/shield.svg)](https://pyup.io/repos/github/spacemanspiff2007/sphinx-exec-code/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sphinx-exec-code)
+![PyPI](https://img.shields.io/pypi/v/sphinx-exec-code)
+[![Downloads](https://pepy.tech/badge/sphinx-exec-code/month)](https://pepy.tech/project/sphinx-exec-code)
+
+_A Sphinx extension to run python code in the documentation_
+
+## About
+Sphinx-exec-code allows execution of any python code during the documentation build.
+It's also possible to display the output of the code execution.
+
+With this extension it's easy to ensure that the provided code samples are always working.
+Additionally, it's possible to inspect and print output of the documented code.
+
+## Documentation
+[The full documentation can be found at here](https://sphinx-exec-code.readthedocs.io)
+
+
+## Quick Example
+
+````text
+.. exec-code::
+   :hide_output:
+
+   print('This code will be executed')
+
+   1/0  # <-- This will cause an error during the doc build
+````
+
+
+# Changelog
+#### 0.1 (21.09.2021)
+- Initial Release

requirements.txt

@@ -0,0 +1,4 @@
+pytest==6.2.5
+pre-commit==2.15.0
+sphinx==4.2.0
+sphinx-rtd-theme==1.0.0