{"id":45831171,"url":"https://github.com/ulgens/ruffen-docs","last_synced_at":"2026-02-26T22:11:00.335Z","repository":{"id":330285667,"uuid":"1122230944","full_name":"ulgens/ruffen-docs","owner":"ulgens","description":"Run `ruff` on Python code blocks in documentation files","archived":false,"fork":false,"pushed_at":"2026-01-31T14:23:22.000Z","size":749,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-01T02:00:36.554Z","etag":null,"topics":["docs","formatter","linter","python","ruff"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ulgens.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-24T10:19:03.000Z","updated_at":"2026-01-31T14:23:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ulgens/ruffen-docs","commit_stats":null,"previous_names":["ulgens/ruffen-docs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ulgens/ruffen-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulgens%2Fruffen-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulgens%2Fruffen-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulgens%2Fruffen-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulgens%2Fruffen-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ulgens","download_url":"https://codeload.github.com/ulgens/ruffen-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ulgens%2Fruffen-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29874556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T21:05:00.265Z","status":"ssl_error","status_checked_at":"2026-02-26T20:57:13.669Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","formatter","linter","python","ruff"],"created_at":"2026-02-26T22:10:59.800Z","updated_at":"2026-02-26T22:11:00.327Z","avatar_url":"https://github.com/ulgens.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"============\nruffen-docs\n============\n\n.. image:: https://img.shields.io/pypi/pyversions/ruffen-docs\n   :alt: PyPI - Python Version\n\n.. image:: https://img.shields.io/pypi/v/ruffen-docs.svg\n   :target: https://pypi.org/project/ruffen-docs/\n\n.. image:: https://img.shields.io/github/checks-status/adamchainz/blacken-docs/main\n   :alt: GitHub main branch status\n\n.. TODO: Use a dynamic badge\n.. image:: https://img.shields.io/badge/Coverage-100%25-success\n  :target: https://github.com/ulgens/ruffen-docs/actions?workflow=CI\n\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\n   :target: https://github.com/astral-sh/ruff\n   :alt: ruff\n\n.. image:: https://img.shields.io/badge/prek-enabled-orange\n   :target: https://github.com/j178/prek\n   :alt: prek enabled\n\nRun `ruff \u003chttps://pypi.org/project/ruff/\u003e`__ on Python code blocks in documentation files.\n\nInstallation\n============\n\nUse **pip**:\n\n.. code-block:: sh\n\n    python -m pip install ruffen-docs\n\nPython 3.10 to 3.14 supported.\n\nruff 0.14.1+ supported.\n\npre-commit hook\n---------------\n\nYou can also install ruffen-docs as a `pre-commit \u003chttps://pre-commit.com/\u003e`__ hook.\nAdd the following to the ``repos`` section of your ``.pre-commit-config.yaml`` file (`docs \u003chttps://pre-commit.com/#plugins\u003e`__):\n\n.. code-block:: yaml\n\n    -   repo: https://github.com/ulgens/ruffen-docs\n        rev: \"\"  # replace with latest tag on GitHub\n        hooks:\n        -   id: ruffen-docs\n            additional_dependencies:\n            - ruff==0.14.1\n\nThen, reformat your entire project:\n\n.. code-block:: sh\n\n    pre-commit run ruffen-docs --all-files\n\nSince ruff is a moving target, it’s best to pin it in ``additional_dependencies``, and upgrade as appropriate.\nIf you have ruff installed as another hook, you can automate upgrading this pinned hook using `sync-pre-commit-deps \u003chttps://github.com/pre-commit/sync-pre-commit-deps\u003e`__.\n\nUsage\n=====\n\nruffen-docs is a command line tool that rewrites documentation files in place.\nIt supports Markdown, reStructuredText, and LaTex files.\nAdditionally, you can run it on Python files to reformat Markdown and reStructuredText within docstrings.\n\nRun ``ruffen-docs`` with the filenames to rewrite:\n\n.. code-block:: sh\n\n    ruffen-docs README.rst\n\nIf any file is modified, ``ruffen-docs`` exits nonzero.\n\n``ruffen-docs`` does not have any ability to recurse through directories.\nUse the pre-commit integration, globbing, or another technique for applying to many files.\nFor example, |with git ls-files pipe xargs|_:\n\n.. |with git ls-files pipe xargs| replace:: with ``git ls-files | xargs``\n.. _with git ls-files pipe xargs: https://adamj.eu/tech/2022/03/09/how-to-run-a-command-on-many-files-in-your-git-repository/\n\n.. code-block:: sh\n\n    git ls-files -z -- '*.md' | xargs -0 ruffen-docs\n\n…or PowerShell’s |ForEach-Object|__:\n\n.. |ForEach-Object| replace:: ``ForEach-Object``\n__ https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/foreach-object\n\n.. code-block:: powershell\n\n    git ls-files -- '*.md' | %{ruffen-docs $_}\n\nruffen-docs currently passes the following options through to ruff:\n\n* |-l / --line-length|__\n\n  .. |-l / --line-length| replace:: ``-l`` / ``--line-length``\n  __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#l-line-length\n\n* |--preview|__\n\n  .. |--preview| replace:: ``--preview``\n  __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#preview\n\n* |--pyi|__\n\n  .. |--pyi| replace:: ``--pyi``\n  __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#pyi\n\n* |-S / --skip-string-normalization|__\n\n  .. |-S / --skip-string-normalization| replace:: ``-S`` / ``--skip-string-normalization``\n  __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#s-skip-string-normalization\n\n* |-t / --target-version|__\n\n  .. |-t / --target-version| replace:: ``-t`` / ``--target-version``\n  __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#t-target-version\n\nIt also has the below extra options:\n\n* ``--check`` - Don’t modify files but indicate when changes are necessary with a message and non-zero return code.\n* ``-E`` / ``--skip-errors`` - Don’t exit non-zero for errors from Black (normally syntax errors).\n* ``--rst-literal-blocks`` - Also format literal blocks in reStructuredText files (more below).\n\nHistory\n=======\n\nruffen-docs is a fork of `blacken-docs \u003chttps://github.com/adamchainz/blacken-docs/\u003e`__. The project is currently maintained by @ulgens.\n\nSupported code block formats\n============================\n\nruffen-docs formats code blocks matching the following patterns.\n\nMarkdown\n--------\n\nIn “python” blocks:\n\n.. code-block:: markdown\n\n    ```python\n    def hello():\n        print(\"hello world\")\n    ```\n\nAnd “pycon” blocks:\n\n.. code-block:: markdown\n\n    ```pycon\n\n    \u003e\u003e\u003e def hello():\n    ...     print(\"hello world\")\n    ...\n\n    ```\n\nPrevent formatting within a block using ``ruffen-docs:off`` and ``ruffen-docs:on`` comments:\n\n.. code-block:: markdown\n\n    \u003c!-- ruffen-docs:off --\u003e\n    ```python\n    # whatever you want\n    ```\n    \u003c!-- ruffen-docs:on --\u003e\n\nWithin Python files, docstrings that contain Markdown code blocks may be reformatted:\n\n.. code-block:: python\n\n    def f():\n        \"\"\"docstring here\n\n        ```python\n        print(\"hello world\")\n        ```\n        \"\"\"\n\nreStructuredText\n----------------\n\nIn “python” blocks:\n\n.. code-block:: rst\n\n    .. code-block:: python\n\n        def hello():\n            print(\"hello world\")\n\nIn “pycon” blocks:\n\n.. code-block:: rst\n\n    .. code-block:: pycon\n\n        \u003e\u003e\u003e def hello():\n        ...     print(\"hello world\")\n        ...\n\nPrevent formatting within a block using ``ruffen-docs:off`` and ``ruffen-docs:on`` comments:\n\n.. code-block:: rst\n\n    .. ruffen-docs:off\n\n    .. code-block:: python\n\n        # whatever you want\n\n    .. ruffen-docs:on\n\nUse ``--rst-literal-blocks`` to also format `literal blocks \u003chttps://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks\u003e`__:\n\n.. code-block:: rst\n\n    An example::\n\n        def hello():\n            print(\"hello world\")\n\nLiteral blocks are marked with ``::`` and can be any monospaced text by default.\nHowever Sphinx interprets them as Python code `by default \u003chttps://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks\u003e`__.\nIf your project uses Sphinx and such a configuration, add ``--rst-literal-blocks`` to also format such blocks.\n\nWithin Python files, docstrings that contain reStructuredText code blocks may be reformatted:\n\n.. code-block:: python\n\n    def f():\n        \"\"\"docstring here\n\n        .. code-block:: python\n\n            print(\"hello world\")\n        \"\"\"\n\nLaTeX\n-----\n\nIn minted “python” blocks:\n\n.. code-block:: latex\n\n    \\begin{minted}{python}\n    def hello():\n        print(\"hello world\")\n    \\end{minted}\n\nIn minted “pycon” blocks:\n\n.. code-block:: latex\n\n    \\begin{minted}{pycon}\n    \u003e\u003e\u003e def hello():\n    ...     print(\"hello world\")\n    ...\n    \\end{minted}\n\nIn PythonTeX blocks:\n\n.. code-block:: latex\n\n    \\begin{pycode}\n    def hello():\n        print(\"hello world\")\n    \\end{pycode}\n\nPrevent formatting within a block using ``ruffen-docs:off`` and ``ruffen-docs:on`` comments:\n\n.. code-block:: latex\n\n    % ruffen-docs:off\n    \\begin{minted}{python}\n    # whatever you want\n    \\end{minted}\n    % ruffen-docs:on\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulgens%2Fruffen-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fulgens%2Fruffen-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fulgens%2Fruffen-docs/lists"}