pyupgrade-docs's Introduction

pyupgrade-docs

Run pyupgrade on python code blocks in documentation files.

install

pip install pyupgrade-docs

usage

pyupgrade-docs provides a single executable (pyupgrade-docs) which will modify .rst / .md / .tex files in place.

It currently supports the following pyupgrade options:

--keep-percent-format
--keep-mock
--keep-runtime-typing
--py3-plus --py3-only
--py36-plus
--py37-plus
--py38-plus
--py39-plus
--py310-plus

The following additional parameters can be used:

-E / --skip-errors

pyupgrade-docs will format code in the following block types:

(markdown)

    ```python
    def hello():
        print("hello world")
    ```

(markdown pycon)

    ```pycon

    >>> def hello():
    ...     print("hello world")
    ...

    ```

(rst)

    .. code-block:: python

        def hello():
            print("hello world")

(rst pycon)

    .. code-block:: pycon

        >>> def hello():
        ...     print("hello world")
        ...

(latex)

\begin{minted}{python}
def hello():
    print("hello world")
\end{minted}

(latex pycon)

\begin{minted}{pycon}
>>> def hello():
...     print("hello world")
...
\end{minted}

(latex with pythontex)

\begin{pycode}
def hello():
    print("hello world")
\end{pycode}

(markdown/rst in python docstrings)

def f():
    """docstring here

    .. code-block:: python

        print("hello world")

    ```python
    print("hello world")
    ```
    """

usage with pre-commit

See pre-commit for instructions

Sample .pre-commit-config.yaml:

-   repo: https://github.com/verhovsky/pyupgrade-docs
    rev: v0.3.0
    hooks:
    -   id: pyupgrade-docs

pyupgrade-docs's People

Contributors

Stargazers

Watchers

pyupgrade-docs's Issues

`--exit-zero-even-if-changed` option does not work

The --exit-zero-even-if-changed option does not work.
When calling git ls-files 'doc/**.md' README.md | xargs pyupgrade-docs --py38-plus --exit-zero-even-if-changed and some files are modified, it exits with the code 123, just as pyupgrade would without the option --exit-zero-even-if-changed.

Calling the same line but without --exit-zero-even-if-changed does not change the outcome.