rst-to-myst.ipynb

rst-to-myst.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "provenance": [],
      "authorship_tag": "ABX9TyPv+NmXrFhV8QHYXwhMeW6o",
      "include_colab_link": true
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "view-in-github",
        "colab_type": "text"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/gist/sgbaird/93b7917632115bcd6c1503bc0c647497/rst-to-myst.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "# RST-to-MyST\n",
        "\n",
        "> Note: this notebook is derived from [`index.md`](https://github.com/executablebooks/rst-to-myst/blob/main/docs/source/index.md).\n",
        "\n",
        "A tool for converting [ReStructuredText](https://docutils.sourceforge.io/) to [MyST Markdown](https://myst-parser.readthedocs.io/).\n",
        "\n",
        "## Getting Started\n",
        "\n",
        "To install from PyPI:"
      ],
      "metadata": {
        "id": "bVMCLov31Kjy"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "umKHUaGZ04JN"
      },
      "outputs": [],
      "source": [
        "%pip install \"rst-to-myst[sphinx]\""
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "Note that the recommended way to install on your local machine is into an isolated environment such as Anaconda or pipx. For example:\n",
        "```python\n",
        "pipx install \"rst-to-myst[sphinx]\"\n",
        "```\n",
        "\n",
        "First, we'll create a folder named `docs` for our documentation."
      ],
      "metadata": {
        "id": "n1XvcUhR2pSK"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "%mkdir docs"
      ],
      "metadata": {
        "id": "XRev1wPG4l8j"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "Next, we'll create an example RST file (`example.rst`) using special Google Colab `%%writefile` syntax. Feel free to adjust the file contents as desired. After running the following cell and clicking refresh in Colab's file explorer, you should be able to see it."
      ],
      "metadata": {
        "id": "TTbZPkw94u0T"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "%%writefile docs/example.rst\n",
        ".. raw:: html\n",
        "\n",
        "    <a href=\"testurl\">testurl</a>"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "R4QEN84K06o_",
        "outputId": "794e93fa-096b-4455-fcbb-917c3383a47e"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Writing docs/example.rst\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "To run a basic conversion of the file:"
      ],
      "metadata": {
        "id": "K5CxZjmI3ROA"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "!rst2myst convert docs/example.rst"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "Qazkzb9q1Dmf",
        "outputId": "d8f05990-9e70-4891-a97d-ac8591d3c603"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "\u001b[34mdocs/example.rst -> docs/example.md\u001b[0m\n",
            "\u001b[32mCONVERTED (extensions: [])\u001b[0m\n",
            "\n",
            "\u001b[32mFINISHED ALL! (extensions: [])\u001b[0m\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "Then view the results:"
      ],
      "metadata": {
        "id": "pXeYqoOu3Z6J"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "!cat docs/example.md"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "hKSQyNoL1GVV",
        "outputId": "d7172ef5-ef34-49c6-b816-a34cbf3aeaf5"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "```{raw} html\n",
            "<a href=\"testurl\">testurl</a>\n",
            "```\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Extra\n",
        "\n",
        "To run it for all files in a project, you could use for example:\n",
        "```python\n",
        "rst2myst convert docs/**/*.rst\n",
        "```\n",
        "\n",
        "For greater control, you can pass configuration with CLI options, or via a YAML configuration file:\n",
        "```python\n",
        "rst2myst convert --config config.yaml docs/**/*.rst\n",
        "```\n",
        "\n",
        "`config.yaml`:\n",
        "```yaml\n",
        "language: en\n",
        "sphinx: true\n",
        "extensions:\n",
        "- sphinx_panels\n",
        "default_domain: py\n",
        "consecutive_numbering: true\n",
        "colon_fences: true\n",
        "dollar_math: true\n",
        "conversions:\n",
        "    sphinx_panels.dropdown.DropdownDirective: parse_all\n",
        "```"
      ],
      "metadata": {
        "id": "n4DJ0IMx3rMK"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Next Steps\n",
        "\n",
        "Read more at https://rst-to-myst.readthedocs.io/"
      ],
      "metadata": {
        "id": "byIRgcWV4JOa"
      }
    }
  ]
}