-m yobx render-gallery … convert a sphinx-gallery example to RST

The command parses a sphinx-gallery Python example file (.py) and writes the equivalent RST source to the corresponding auto_examples_<category>/ folder without executing any code.

For an input file at docs/examples/<category>/plot_foo.py the output is written to docs/auto_examples_<category>/plot_foo.rst. The output directory is created automatically if it does not exist.

Description

See yobx.helpers._gallery_helper.gallery_to_rst() and yobx._command_lines_parser._gallery_auto_output_path().

    usage: render-gallery [-h] [-v VERBOSE] inputs [inputs ...]
    
    Converts a sphinx-gallery Python example file (.py) to RST without
    executing any code and writes the result to the corresponding
    auto_examples_<category>/ folder.
    
    A sphinx-gallery example file consists of:
      - A module docstring (verbatim RST: title, description, labels, …)
      - Python code blocks separated by ``# %%`` section markers
      - Comment lines following ``# %%`` are treated as RST prose
    
    For an input file at ``docs/examples/<category>/plot_foo.py`` the
    output is written to ``docs/auto_examples_<category>/plot_foo.rst``.
    
    positional arguments:
      inputs                sphinx-gallery Python file(s) to convert to RST.
    
    options:
      -h, --help            show this help message and exit
      -v VERBOSE, --verbose VERBOSE
                            verbosity
    
    examples:
    
        # Convert a single gallery example
        python -m yobx render-gallery docs/examples/core/plot_dot_graph.py
    
        # Convert several examples at once
        python -m yobx render-gallery \
            docs/examples/core/plot_dot_graph.py \
            docs/examples/sklearn/plot_sklearn_pipeline.py

Examples

Convert a single gallery example:

python -m yobx render-gallery docs/examples/core/plot_dot_graph.py

Convert several examples at once:

python -m yobx render-gallery \\
    docs/examples/core/plot_dot_graph.py \\
    docs/examples/sklearn/plot_sklearn_pipeline.py