Utilisation

Activer le plugin

Ajouter dans votre fichier mkdocs.yml:

plugins:
  - search
  - sqlite-console

Note

Si vous n'avez aucune entrée dans la section plugins de votre fichier de configuration, vous voudrez sans doute ajouter le plugin search. MkDocs l'active par défaut s'il n'y a pas d'autres plugins, et dans le cas contraire, MkDocs demande de l'activer explicitement.

Utilisation avec mkdocs-macros-plugin ou Pyodide-MkDocs-Theme

Noter que le plugin mkdocs-sqlite-console doit toujours être référencé après les plugins de PMT ou des macros, dans le fichier mkdocs.yml :

plugins:
    - search
    - macros            # avec mkdocs-macros-plugin
    - sqlite-console

plugins:
    - search
    - pyodide_macros    # avec PMT
    - sqlite-console

Si vous voulez déployer votre site (à l'aide de mkdocs build ou mkdocs gh-deploy), il faut également ajouter à votre fichier mkdocs.yml une ligne du type

site_url: https://monsite.url/chemin

Par exemple, ce site est configuré avec

site_url: https://epithumia.github.io/mkdocs-sqlite-console

site_url

Si vous n'avez pas défini la variable site_url dans votre fichier mkdocs.yml, les commandes mkdocs build et mkdocs gh-deploy ne fonctionneront pas et signaleront la nécessité de le faire.

Afficher la console/IDE

Paramètres

On peut afficher une console/IDE SQLite grâce à la commande {{ sqlide paramètres }}. Cette commande accepte quatre paramètres, tous optionnels :

un titre : par exemple titre="Exercice 1". Par défaut, le titre est "sql"
un chemin vers un script SQL d'initialisation, init : par exemple init=sql/init.md
un chemin vers une base SQLite : par exemple bases/test.db
un chemin vers un fichier de code sql pré-saisi dans l'IDE : par exemple sql="sql/code.sql"
si le mot clef autoexec est présent, alors le contenu de code sera exécuté comme si l'utilisateur avait cliqué le bouton

Astuce

A part pour le titre, les apostrophes ou guillemets sont optionnels. Ainsi, sql="sql/code.sql", sql='sql/code.sql' et sql=sql/code.sql sont équivalents.

Attention

le titre doit être entre guillemets
les chemins vers les fichiers sont relatifs à la racine du site
les chemins ne peuvent pas contenir d'espace
les options base et init sont mutuellement exclusives ; l'option base est prioritaire.

Voir le cas des utilisations en tant que macro, où les syntaxes diffèrent légèrement.

Quelques exemples

Affichage basique

Pour afficher un IDE avec du code SQL d'initialisation et du code pré-saisi :

{{ sqlide titre="IDE avec initialisation et code pré-saisi" init="sql/init1.sql" sql="sql/code.sql" }}

On obtient l'affichage ci-dessous :

IDE avec initialisation et code pré-saisi

On peut aussi charger une base directement :

{{sqlide titre="IDE avec une base binaire chargée et code pré-saisi autoexécuté" base="bases/test.db" sql="sql/code.sql" autoexec}}

IDE avec une base binaire chargée et code pré-saisi autoexécuté

Cacher l'IDE

Si l'on ne veut que le résultat de la requête sans pour autant afficher l'IDE, il suffit d'ajouter l'option hide :

{{sqlide titre="IDE avec une base binaire chargée et code pré-saisi autoexécuté, IDE caché" base="bases/test.db" sql="sql/code.sql" autoexec hide}}

Sql

Titre

Attention, le titre n'est plus affiché dans ce cas.

Base partagée entre plusieurs consoles

Il est possible de donner un argument supplémentaire pour partager une base entre plusieurs consoles/IDE :

{{ sqlide titre="IDE avec initialisation dans l'espace bdd1" init="sql/init1.sql" espace="bdd1" }}

{{ sqlide titre="IDE sans initialisation, avec code pré-saisi, dans l'espace bdd1" sql="sql/code.sql" espace=bdd1}}

IDE avec initialisation dans l'espace bdd1

IDE sans initialisation, avec code pré-saisi, dans l'espace bdd1

Utilisation dans les admonitions de mkdocs-material

On peut appeler le code à l'intérieur d'une admonition :

!!! sql "Bloc admonition avec initialisation et code pré-saisi"
    {{ sqlide titre="Init + Code" init="sql/init1.sql" sql="sql/code.sql" }}

donne :

Bloc admonition avec initialisation et code pré-saisi

Init + Code

???+ sql "Bloc accordéon avec initialisation et code pré-saisi"
    {{ sqlide titre="Init + Code" init="sql/init1.sql" sql="sql/code.sql" }}

donne :

Bloc accordéon avec initialisation et code pré-saisi

Init + Code

Usage avec le plugin des macros MkDocs ou Pyodide-MkDocs-Theme

mkdocs-sqlite-console est compatible avec l'utilisation du plugin mkdocs-macros-plugin, ainsi que le thème Pyodide-MkDocs-Theme.

Si l'un des deux est utilisé (avec une manipulation de configuration à faire pour le plugin des macros seul), il est alors possible de déclarer un sqlide via un appel de macro :

{{ sqlide(titre="Init + Code", init="sql/init1.sql", sql="sql/code.sql") }}

Syntaxes

Par rapport à l'utilisation normale du plugin, il faut :

Ajouter les parenthèses autour des arguments,
Ajouter des virgules entre les arguments,
Les guillemets autour des valeurs des arguments sont alors indispensables.
Les arguments passés sous forme de chaînes de caractères seule, dans la syntaxe originale (autoexec, hide), doivent être passés sous forme de booléens. On peut aussi utiliser des entiers pour raccourcir les déclaration : 0 ou 1.

Signature exacte de la macro

Voici la déclaration exacte de la macro, et les valeurs par défaut associées aux différents arguments :

sqlide(
    self,
    titre='Sql',
    sql='',
    espace=None,
    *,
    base='/',
    init='',
    hide=False,
    autoexec=False,
)

Les trois premiers arguments, titre, sql et espace sont des arguments positionnels avec des valeurs par défaut : il n'est pas obligatoire de mettre le nom de l'argument (mais dans ce cas, il faut respecter l'ordre de déclaration).
Les arguments après *, sont des arguments nommés. Ils doivent impérativement être renseignés en précisant le nom de l'argument.
Il est toujours possible de renseigner les noms des arguments positionnels si on le souhaite (dans ce cas, il n'est pas indispensable de respecter leur ordre dans la déclaration).

L'appel de l'exemple ci-dessus peut donc également se faire comme suit :

{{ sqlide("Init + Code", "sql/code.sql", init="sql/init1.sql") }}

Anciennes syntaxes - versions 1.0.7 et antérieures

Ceci décrit les anciens comportements pour utiliser mkdocs-sqlite-console avec le plugin des macros ou PMT activés. Ces méthodes restent utilisables.

Le plugin macros utilise les doubles accolades pour définir ses propres blocs de code, ce qui empêche ce plugin de fonctionner normalement. En conséquence, quand le plugin macros est détecté, la syntaxe change et l'IDE SQLite est chargée avec la syntaxe suivante :

{!{ sqlide paramètres }!}

Par exemple, l'appel :

{{ sqlide titre="..." init="sql/init1.sql" sql="sql/code.sql" }}

...devait alors s'écrire :

{!{ sqlide titre="..." init="sql/init1.sql" sql="sql/code.sql" }!}

Activation

`Pyodide-MkDocs-Theme`

Le thème gère tout automatiquement, à partir de sa version 4.4.6.

Les versions antérieures nécessitent d'utiliser les anciennes syntaxes de déclaration des sqlide, ou de mettre en place la logistique décrite ci-dessous pour mkdocs-macros-plugin.

`mkdocs-macros-plugin`

Dans le cas de l'utilisation du plugin des macros seul, il est nécessaire d'enregistrer la macro depuis votre fichier/module de macros personnalisées.

Par défaut, il s'agit du fichier main.py :

def define_env(env):

    # Vos macros personnalisées ici:
    ...

    # Enregistrement de la macro sqlide:
    sql_plugin = env._conf.plugins['sqlite-console']
    env.macro(sql_plugin.sqlide)

Erreurs

Le plugin détectera les fichiers non existants :

{{sqlide titre="Erreur fichier base manquant" base=bases/basem.db sql=sql/code1.sql }}

Erreur fichier base manquant

{{sqlide titre="Erreur fichier sql manquant" init=sql/initm.sql sql=sql/codem.sql }}

Erreur fichier sql manquant