pax_global_header00006660000000000000000000000064142342332670014520gustar00rootroot0000000000000052 comment=3a7a3300934249b9e32eccd0fbcdd39b3ab9e76c sphinx-examples-0.0.5/000077500000000000000000000000001423423326700146475ustar00rootroot00000000000000sphinx-examples-0.0.5/.github/000077500000000000000000000000001423423326700162075ustar00rootroot00000000000000sphinx-examples-0.0.5/.github/workflows/000077500000000000000000000000001423423326700202445ustar00rootroot00000000000000sphinx-examples-0.0.5/.github/workflows/tests.yml000066400000000000000000000032301423423326700221270ustar00rootroot00000000000000# Test that the documentation builds and publish if a new tag is pushed. name: build-docs on: push: branches: [main] tags: - 'v*' pull_request: env: # Force colors for logs PY_COLORS: 1 FORCE_COLOR: True jobs: pre-commit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python 3.8 uses: actions/setup-python@v3 with: python-version: 3.8 - uses: pre-commit/action@v2.0.3 docs: runs-on: ubuntu-latest strategy: matrix: python-version: [3.9] steps: - uses: actions/checkout@v3 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v3 with: python-version: ${{ matrix.python-version }} cache: "pip" cache-dependency-path: '**/pyproject.toml' - name: Install Python dependencies run: | python -m pip install --upgrade pip pip install wheel pip install -e .[sphinx] - name: Build documentation run: | sphinx-build docs/ docs/_build/html -W publish: name: Publish to PyPi needs: [pre-commit, docs] if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags') runs-on: ubuntu-latest steps: - name: Checkout source uses: actions/checkout@v3 - name: Set up Python 3.8 uses: actions/setup-python@v3 with: python-version: 3.8 - name: Install flit run: | pip install flit~=3.6 - name: Build and publish run: | flit publish env: FLIT_USERNAME: __token__ FLIT_PASSWORD: ${{ secrets.PYPI_KEY }} sphinx-examples-0.0.5/.gitignore000066400000000000000000000035201423423326700166370ustar00rootroot00000000000000# Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class # C extensions *.so # Distribution / packaging .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ pip-wheel-metadata/ share/python-wheels/ *.egg-info/ .installed.cfg *.egg MANIFEST # PyInstaller # Usually these files are written by a python script from a template # before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *.spec # Installer logs pip-log.txt pip-delete-this-directory.txt # Unit test / coverage reports htmlcov/ .tox/ .nox/ .coverage .coverage.* .cache nosetests.xml coverage.xml *.cover *.py,cover .hypothesis/ .pytest_cache/ _build # Translations *.mo *.pot # Django stuff: *.log local_settings.py db.sqlite3 db.sqlite3-journal # Flask stuff: instance/ .webassets-cache # Scrapy stuff: .scrapy # Sphinx documentation docs/_build # PyBuilder target/ # Jupyter Notebook .ipynb_checkpoints # IPython profile_default/ ipython_config.py # pyenv .python-version # pipenv # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. # However, in case of collaboration, if having platform-specific dependencies or dependencies # having no cross-platform support, pipenv may install dependencies that don't work, or not # install all needed dependencies. #Pipfile.lock # PEP 582; used by e.g. github.com/David-OConnor/pyflow __pypackages__/ # Celery stuff celerybeat-schedule celerybeat.pid # SageMath parsed files *.sage.py # Environments .env .venv env/ venv/ ENV/ env.bak/ venv.bak/ # Spyder project settings .spyderproject .spyproject # Rope project settings .ropeproject # mkdocs documentation /site # mypy .mypy_cache/ .dmypy.json dmypy.json # Pyre type checker .pyre/ # VSCode config .vscode # PyCharm config .idea # OSX .DS_Store sphinx-examples-0.0.5/.pre-commit-config.yaml000066400000000000000000000011051423423326700211250ustar00rootroot00000000000000# Install pre-commit hooks via # pre-commit install exclude: > (?x)^( \.vscode/settings\.json| docs/conf\.py| )$ repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.2.0 hooks: - id: check-json - id: check-yaml - id: end-of-file-fixer - id: trailing-whitespace - repo: https://github.com/pycqa/isort rev: 5.10.1 hooks: - id: isort - repo: https://github.com/psf/black rev: 22.3.0 hooks: - id: black - repo: https://github.com/PyCQA/flake8 rev: 4.0.1 hooks: - id: flake8 sphinx-examples-0.0.5/CHANGELOG.md000066400000000000000000000005211423423326700164560ustar00rootroot00000000000000# Changelog ## v0.0.5 Fix a bug that caused colon fence content to break the directive parsing. ## v0.0.4 Converting to using `{grid}` instead of `{card}` to fix parsing examples with `{card}` directives. ## v0.0.3 Simplifying the user-interface of the resulting CSS. ## v0.0.2 Fixed a CSS path bug. ## v0.0.1 Initial release. sphinx-examples-0.0.5/LICENSE000077500000000000000000000020571423423326700156630ustar00rootroot00000000000000MIT License Copyright (c) 2018 Chris Holdgraf Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. sphinx-examples-0.0.5/MANIFEST.in000077500000000000000000000000131423423326700164020ustar00rootroot00000000000000graft doc/ sphinx-examples-0.0.5/README.md000066400000000000000000000034141423423326700161300ustar00rootroot00000000000000# sphinx-examples A small Sphinx extension to create examples of source markup and the result of rendering it in your documentation. This is useful if you wish to demonstrate the functionality of a new directive or role in Sphinx. 🚨**This is very alpha software**🚨: It is packaged primarily for convience and not heavily tested. Use at your own risk! ## Installation You can install `sphinx-examples` with `pip`: ```bash pip install sphinx-examples ``` ## Usage See [the `sphinx-examples` documentation](https://ebp-sphinx-examples.readthedocs.io/en/latest/) for more information. ## Develop To develop this extension, follow these steps: 1. **Clone the repository locally** ```console $ git clone https://github.com/executablebooks/sphinx-examples $ cd sphinx-examples ``` 2. **Install pre-commit hooks** ```console $ pre-commit install ``` 3. **Install development and documentation dependencies** ```console $ pip install -e .[sphinx] ``` The codebase for this package is in `src/sphinx_examples`. Documentation is in `docs/`. This package has no testing infrastructure, so be careful when using it! If it becomes more complex or with more features, we may add more testing around it in the future. For not it is packaged for convenience and re-use across EBP repositories. ## Build the documentation The documentation is currently not hosted anywhere, so if you'd like to preview the documentation "live", run the following command: ```console pip install -e .[sphinx] sphinx-build docs docs/_build/html ``` Then browse the HTML files in `docs/_build/html` to see the rendered documentation. ## Inspiration This project takes heavy inspiration from the [Bootstrap v5 documenation](https://getbootstrap.com/docs/5.0/utilities/borders/#border). sphinx-examples-0.0.5/docs/000077500000000000000000000000001423423326700155775ustar00rootroot00000000000000sphinx-examples-0.0.5/docs/Makefile000077500000000000000000000011461423423326700172440ustar00rootroot00000000000000# Minimal makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build SPHINXPROJ = SphinxCopybutton SOURCEDIR = . BUILDDIR = _build # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) .PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) sphinx-examples-0.0.5/docs/changelog.md000066400000000000000000000000411423423326700200430ustar00rootroot00000000000000```{include} ../CHANGELOG.md ``` sphinx-examples-0.0.5/docs/conf.py000066400000000000000000000017351423423326700171040ustar00rootroot00000000000000# -- Project information ----------------------------------------------------- project = "Sphinx Examples" copyright = "2022, Executable Books" author = "Executable Books Community" # The short X.Y version version = "" # The full version, including alpha/beta/rc tags release = "" # -- General configuration --------------------------------------------------- extensions = ["myst_parser", "sphinx_copybutton", "sphinx_examples"] templates_path = [] master_doc = "index" language = None exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # -- Options for HTML output ------------------------------------------------- html_theme = "sphinx_book_theme" # html_theme = "sphinx_rtd_theme" # html_theme = "furo" html_theme_options = { "repository_url": "https://github.com/executablebooks/sphinx-examples", "use_repository_button": True, "use_issues_button": True, "use_edit_page_button": True, "home_page_in_toc": True, } myst_enable_extensions = ["colon_fence"] sphinx-examples-0.0.5/docs/index.md000066400000000000000000000035041423423326700172320ustar00rootroot00000000000000# `sphinx-examples` A small sphinx extension to add "example snippets" that allow you to show off source markdown and the result of rendering it in Sphinx. For example: ````{example} Showing off a card and note directive :::{note} Here's a sample note! ::: ```` :::{warning} This currently only works with MyST Markdown content, it will not work if you've written your documentation in reStructuredText. ::: ## Install Install with pip: ```console $ pip install sphinx-examples ``` ## Use The `{example}` directive allows you to show off some source markdown, and the result of rendering it. It is meant to help you demonstrate functionality of a theme, extension, syntax, etc. For example: ````{example} Using the example directive ```{example} Example title Here's my **example**! ``` ```` ### Reverse source and result You can reverse the order of `source` and `result` by using the `:reverse:` flag, like so: ````{example} ```{example} Reversed source and result :reverse: Here's my **example**! ``` ```` You can also remove the parent container of the source/result blocks in case you wish to demonstrate something that would not work properly inside a container: ### Remove the container with simple mode You can remove the Sphinx Design container entirely, which simply places the source / result next to one another. This is useful if the container would prevent you from demonstrating some functionality: ````{example} No container so we can show off a margin :no-container: ```{example} :no-container: :::{margin} Here's my **margin content**! ::: ``` ```` ### Add your own class You can add your own classes to examples as well. For example: ````{example} :no-container: ```{example} A full-width example :class: full-width :no-container: :::{note} A full-width note! ::: ``` ```` ```{toctree} reference changelog ``` sphinx-examples-0.0.5/docs/reference.md000066400000000000000000000011231423423326700200540ustar00rootroot00000000000000# Reference examples The following examples show off the look and feel of this extension. They also serve as an informal test-suite - none of them should result in problematic output or warnings. As we discover edge-cases and bugs, add new examples below to confirm they work once fixed. ## `{card}` directive ````{example} Card directive with a header should be properly parsed. ```{card} :class-header: bg-light A note! ^^^ :::{note} Here's a sample note! ::: ``` ```` ## Colon fence ````{example} Example with colon fence should not result in kwarg error :::{note} A note! ::: ```` sphinx-examples-0.0.5/pyproject.toml000066400000000000000000000033671423423326700175740ustar00rootroot00000000000000[build-system] requires = ["flit_core >=3.5,<4"] build-backend = "flit_core.buildapi" [project] name = "sphinx-examples" authors = [{name = "Executable Book Project", email = "executablebooks@gmail.com"}] classifiers = [ "Development Status :: 4 - Beta", "License :: OSI Approved :: BSD License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: Implementation :: CPython", "Topic :: Software Development :: Libraries :: Python Modules", "Topic :: Text Processing :: Markup", ] keywords = [ "documentation", "sphinx", ] dynamic = ["description", "version"] requires-python = ">=3.7" dependencies = [ "sphinx>4", "sphinx-design", ] [project.license] file = "LICENSE" [project.readme] file = "README.md" content-type = "text/markdown" [project.urls] Homepage = "https://executablebooks.org/" Documentation = "https://executablebooks.org/" Funding = "https://executablebooks.org" Source = "https://github.com/executablebooks/sphinx-examples/" Tracker = "https://github.com/executablebooks/sphinx-examples/issues" [project.optional-dependencies] sphinx = [ "sphinx-book-theme", "sphinx-copybutton", "myst-parser", # Extra theme dependencies to test "sphinx-rtd-theme", "furo", ] [tool.flit.module] name = "sphinx_examples" [tool.flit.sdist] include = [ "src/sphinx_examples/_static/" ] exclude = [ ".*", # Any hidden folders or files "docs/", "tests/", "scripts/", "tox.ini", "codecov.yml", "conftest.py", ] [tool.isort] profile = "black" sphinx-examples-0.0.5/readthedocs.yml000077500000000000000000000001761423423326700176660ustar00rootroot00000000000000version: 2 python: version: 3 install: - method: pip path: . extra_requirements: - sphinx sphinx-examples-0.0.5/src/000077500000000000000000000000001423423326700154365ustar00rootroot00000000000000sphinx-examples-0.0.5/src/sphinx_examples/000077500000000000000000000000001423423326700206455ustar00rootroot00000000000000sphinx-examples-0.0.5/src/sphinx_examples/__init__.py000066400000000000000000000103561423423326700227630ustar00rootroot00000000000000"""A lightweight example directive to make it easy to demonstrate code / results.""" import os from typing import List from docutils import nodes from docutils.parsers.rst import directives from sphinx.util.docutils import SphinxDirective __version__ = "0.0.5" TEMPLATE_GRID = """ `````````````````````````````````````{{grid}} :gutter: 0 :margin: 0 2 0 0 :padding: 0 :class-container: sd-example {content} ````````````````````````````````````` """ TEMPLATE_TITLE = """ ````````````````````````````````````{{grid-item}} :columns: 12 :class: sd-example-title {content} ```````````````````````````````````` """ TEMPLATE_SOURCE = """ ````````````````````````````````````{{grid-item}} :columns: 12 :class: sd-example-item sd-example-source {extra_classes} ``````````````````````````````markdown {content} `````````````````````````````` ```````````````````````````````````` """ TEMPLATE_RESULT = """ ````````````````````````````````````{{grid-item}} :columns: 12 :class: sd-example-item p-3 sd-example-result {extra_classes} ```````````````````````````````````{{div}} result-content {content} ``````````````````````````````````` ```````````````````````````````````` """ TEMPLATE_SIMPLE = """ **Source** ````````````````````````````markdown {content} ```````````````````````````` **Result** {content} """ TEMPLATE_SIMPLE_REVERSED = """ **Result** {content} **Source** ````````````````````````````markdown {content} ```````````````````````````` """ def st_static_path(app): static_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "_static")) app.config.html_static_path.append(static_path) class ExampleDirective(SphinxDirective): """A directive to show source / result content blocks.""" name = "example" has_content = True required_arguments = 0 optional_arguments = 1 final_argument_whitespace = True option_spec = { "class": directives.class_option, "reverse": directives.flag, "no-container": directives.flag, } def run(self) -> List[nodes.Node]: content_text = "\n".join(self.content) grid_items = [] # Parse the template with Sphinx Design to create an output container = nodes.container() # Remove the container styling if requested if "no-container" in self.options: if "reverse" in self.options: simple_text = TEMPLATE_SIMPLE_REVERSED.format(content=content_text) else: simple_text = TEMPLATE_SIMPLE.format(content=content_text) if self.arguments: simple_text = f"**{self.arguments[0]}**\n\n" + simple_text self.state.nested_parse([simple_text], 0, container) else: # If we have a title, add it above the source code if self.arguments: grid_items.append(TEMPLATE_TITLE.format(content=self.arguments[0])) content_templates = [TEMPLATE_SOURCE, TEMPLATE_RESULT] if "reverse" in self.options: content_templates = content_templates[::-1] extra_classes = ["sd-rounded-top", "sd-rounded-bottom"] for (template, classes) in zip(content_templates, extra_classes): template = template.format(content=content_text, extra_classes=classes) grid_items.append(template) # Use Sphinx Design to parse content grid_text = TEMPLATE_GRID.format(content="\n".join(grid_items)) self.state.nested_parse([grid_text], 0, container) # Sphinx Design outputs a container too, so just use that container = container.children[0] # Add extra classes if self.options.get("class", []): container.attributes["classes"] += self.options.get("class", []) return [container] # We connect this function to the step after the builder is initialized def setup(app): # Activate Sphinx design app.setup_extension("sphinx_design") # Add our static path app.connect("builder-inited", st_static_path) app.add_css_file("styles/sphinx-examples.css") # Add directives app.add_directive("example", ExampleDirective) return { "version": __version__, "parallel_read_safe": True, "parallel_write_safe": True, } sphinx-examples-0.0.5/src/sphinx_examples/_static/000077500000000000000000000000001423423326700222735ustar00rootroot00000000000000sphinx-examples-0.0.5/src/sphinx_examples/_static/styles/000077500000000000000000000000001423423326700236165ustar00rootroot00000000000000sphinx-examples-0.0.5/src/sphinx_examples/_static/styles/sphinx-examples.css000066400000000000000000000014111423423326700274520ustar00rootroot00000000000000/** * Example directive styling */ .sd-example-title p { margin: 0 0 .2em 0; font-size: .9em; font-style: italic; } .sd-example-item { border: 1px solid var(--sd-color-card-border); } .sd-example-source div[class*="highlight-"], .sd-example-source div.highlight, .sd-example-source pre { margin: 0; border: none; box-shadow: none; border-radius: .25rem; /* Same as .sd-card */ } .sd-example-source pre { padding: 1.5rem 1rem; } /* Cards should be flush w/ one another at their intersection */ .sd-example .sd-rounded-bottom { border-bottom-right-radius: .25rem; border-bottom-left-radius: .25rem; } .sd-example .sd-rounded-top { border-top-right-radius: .25rem; border-top-left-radius: .25rem; border-bottom: 0; } sphinx-examples-0.0.5/tox.ini000066400000000000000000000015641423423326700161700ustar00rootroot00000000000000# To use tox, see https://tox.readthedocs.io [tox] envlist = py39-sphinx3 isolated_build = True passenv=TERM # Use tox.ini for flake8 config because it does not yet support pyproject.toml [flake8] max-line-length = 100 extend-ignore = E203 [testenv] # only recreate the environment when we use `tox -r` recreate = false [testenv:docs] description = Build the documentation extras = sphinx deps = ipython -e. commands = sphinx-build \ -n -b {posargs:html} docs/ docs/_build/{posargs:html} [testenv:docs-live] description = Auto-build and preview the documentation in the browser deps = sphinx-autobuild ipython extras = sphinx commands = pip install -e . sphinx-autobuild \ --re-ignore _build/.* \ --watch sphinx_examples \ --port 0 --open-browser \ -n -b {posargs:html} docs/ docs/_build/{posargs:html}