VS Code rST Config

OS-Environment für rST/Sphinx

Auf der fraglichen Linux/WSL2 Umgebung müssen die nötigen Python3 und Sphinx Build Techniken installiert sein.

sudo apt install python3-full python3-pip                                    # for Python
# if you want make latexpdf:
sudo apt install texlive-full texlive-fonts-extra texlive-fonts-recommended  # 6 to 7 GB!

Python3 VENV - Virtual Environments

Wir müssen seit mehreren Python3 Versionen eine Umgebung für das Installieren von Python3 Erweiterungen - den Modulen - erschaffen. Ich wähle die Grundtechnik VENV:

# Basedir for Virtual env
mkdir -p $HOME/.venvs

# make a new Dir a new VENV Home
python3 -m venv $HOME/.venvs/MyEnv

# don't forget to tell your shell
# source ~/.venvs/MyEnv/bin/activate

Jetzt kann man für die Python (VENV) Umgebung die entsprechenden Module installieren: python3 -m pip -r requirements.txt.

Oder aber natürlich manuell für die fraglichen Module der rST und Sphinx Umsetzungen in VS Code:

python3 -m pip install esbonio             # Language Server for Sphinx Docs
python3 -m pip install sphinx==6.2.1       # Dokumentationswerkzeug - Version TYPO3 readthedoc Theme
python3 -m pip install sphinx-copybutton   # Sphinx Extension
python3 -m pip install sphinx_tabs         # if needed - see conf.py

VS Code Extensions and Settings

Wir benötigen die folgenden Extensions:

• Esbonio - Language Server (LSP)

• reStructuredText Syntax highlighting

• reStructuredText - optional - Code Snippets

Microsoft VS Code Settings in .vscode/settings.json für Live-Preview und sauberes Building der Dokumente:

{
    "esbonio.sphinx.confDir": "${workspaceFolder}",
    "esbonio.sphinx.buildDir": "${workspaceFolder}/_build",
    "restructuredtext.linter.run": "off"
}

Wichtig ist die Zeile für den _build Pfad! Weitere Infos zur verwendeten Sphinx/reStructuredText Technik folgen.

Profitipp: eigene Snippets für reStructuredText

In VS Code: Konfiguration - Codeausschnitte (Snippets) - reStructuredText

Es öffnet sich eine kommentierte JSON, die selbstverständlich Fehler zeigt, da JSON-Formate ja keinerlei Kommentierungen unterstützen ;-) !

Pfad bei Nutzung von VS Code Profilen: ~/.config/Code/User/profiles/-7c2d9dac/snippets/restructuredtext.json.

Beispielcode für eigene restructuredText Snippets:

{
   "For Loop": {
      "prefix": [
         "jbfor",
         "jbfor-const"
      ],
      "body": [
         "for (const ${2:element} of ${1:array}) {",
         "\t$0",
         "}"
      ],
      "description": "A for loop."
   },
   "For Hyperlinks": {
      "prefix": [
         "jblink"
      ],
      "body": [
         "`${1:linktitle} <${2:linkref}>`_"
      ],
      "description": "A snippet for reStructuredText Hyperlinks."
   }
}

Der erste Block ist aus der vorgeschlagenen Hilfe von VS Code zum Thema: Create your own snippets.

Der zweite Block zeigt eine beispielhafte Lösung für eine Hyperlink mit reStructuredText Dokumenten.