From f685651197b2b25476096d54a2b607a4d172643c Mon Sep 17 00:00:00 2001
From: Jean Sirmai <jean@a-lec.org>
Date: Sun, 6 Oct 2024 00:43:36 +0200
Subject: [PATCH] WIP: python3 > script > automatic docstrings parsing

---
 {audit => audits}/2024-07-14          |  0
 read_me.doc                           | 27 ++++++++++++++++-----------
 scripts/Hello World, I'm back ! 😄.py |  7 +++++++
 scripts/doctext                       |  5 -----
 scripts/junk                          |  1 +
 scripts/let_us_read_and_write.py      | 13 +++++++++++++
 scripts/let_us_read_this_file.py      | 20 ++++++++++++++++++++
 scripts/parsing_functions_names       | 11 +++++++++++
 scripts/parsing_functions_names.py    | 11 +++++++++++
 9 files changed, 79 insertions(+), 16 deletions(-)
 rename {audit => audits}/2024-07-14 (100%)
 create mode 100755 scripts/Hello World, I'm back ! 😄.py
 delete mode 100644 scripts/doctext
 create mode 100644 scripts/junk
 create mode 100755 scripts/let_us_read_and_write.py
 create mode 100755 scripts/let_us_read_this_file.py
 create mode 100644 scripts/parsing_functions_names
 create mode 100755 scripts/parsing_functions_names.py

diff --git a/audit/2024-07-14 b/audits/2024-07-14
similarity index 100%
rename from audit/2024-07-14
rename to audits/2024-07-14
diff --git a/read_me.doc b/read_me.doc
index c20fee2..b6bbcee 100644
--- a/read_me.doc
+++ b/read_me.doc
@@ -36,12 +36,12 @@
  *
  *  2)  structure:
  *
- *  texte libre:   que fait la fonction?
- *                 où est-elle définie (dans quel fichier?)
- *                 par quelles fonctions est-elle appelée?
- *  @param         paramètres pris en entrée
- *  @return        valeur retournée en sortie
- *  @use           liste de fonctions GTK appelées par cette fonction, dont:
+ *  texte libre:   décrit ce que fait la fonction,
+ *                 où elle est définie (dans quel fichier),
+ *                 et par quelles fonctions elle est appelée.
+ *  @param         les paramètres pris en entrée
+ *  @return        la valeur retournée en sortie
+ *  @use           la liste de fonctions GTK appelées par cette fonction, dont:
  *  @use_mem?      celles qui doivent être 'free' après usage
  *
  *                 TODO : actuellement, valgrind bin/gem-graph-client détecte :
@@ -115,12 +115,17 @@
  *        setup, shutdown, update, list, sort, seek, select, fix, debug,
  *        render, realize, unrealize, activate, exec, stop, signal,
  *
- *   Le troisième préfixe est choisi dans une liste d'objets.
- *   Ces objets sont ceux sur lesquels agissent les fonctions:
+ *   Le troisième préfixe est choisi dans une liste d'objets ou d'états
+ *   qui sont modifiés par les fonctions.
+ *   Ce préfixe peut être composé de deux, trois ou quatre items
+ *   appartenant à cette liste et d'une conjonction si besoin.
+ *   ex: axis_slider, stack_slot_size, user_tree_model_child,
+ *       grids_on_space_faces_lines, current_model_before_editing, etc.
+ *
  *        number, string, view, image, window, list, tree, stack,
  *        file, buffer, callback, signal,
  *        widget, button, slider, color, glarea, shader,
- *        point, line, plan, space_unit, site, arrow, slot, vertex, ridge,
+ *        point, line, plan, space_unit, site, arrow, slot, vertex, ridge, axis
  *        state, rules, data, results, stock,
  *
  *
@@ -128,8 +133,8 @@
  *  Le 2024-10-05), seules trois fonctions ne sont pas nommées selon ces règles:
  *      >  create_axis_slider, free_stack_slot, free_stack_slot_size <
  *
- *  et les noms de cinq autres peuvent être améliorés.
- *     graphics_shutdown_graphics_stack  >  graphics_shutdown_stack
+ *  et les noms de cinq autres pourraient être améliorés.
+ *     graphics_shutdown_graphics_stack  >  graphics_shutdown_stack  <  ex.
  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  */
 
 
diff --git a/scripts/Hello World, I'm back ! 😄.py b/scripts/Hello World, I'm back ! 😄.py
new file mode 100755
index 0000000..f6158cd
--- /dev/null
+++ b/scripts/Hello World, I'm back ! 😄.py	
@@ -0,0 +1,7 @@
+#!/usr/bin/env python3
+# uses scripts/doctext
+
+#https://python.developpez.com/tutoriels/python-basic-par-exemple/?page=gestion-des-fichiers
+#https://note.nkmk.me/en/python-docstring/
+
+print("Hello World, I'm back ! 😄")
diff --git a/scripts/doctext b/scripts/doctext
deleted file mode 100644
index f8e9d55..0000000
--- a/scripts/doctext
+++ /dev/null
@@ -1,5 +0,0 @@
-#!/usr/bin/env python3
-uses scripts/doctext
-
-https://python.developpez.com/tutoriels/python-basic-par-exemple/?page=gestion-des-fichiers
-https://note.nkmk.me/en/python-docstring/
diff --git a/scripts/junk b/scripts/junk
new file mode 100644
index 0000000..954590a
--- /dev/null
+++ b/scripts/junk
@@ -0,0 +1 @@
+ *   C O N V E N T I O N S   E T   R È G L E S   D E   N O M M A G E  -  2 0 2 4
diff --git a/scripts/let_us_read_and_write.py b/scripts/let_us_read_and_write.py
new file mode 100755
index 0000000..954c49e
--- /dev/null
+++ b/scripts/let_us_read_and_write.py
@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+
+rr = open('read_me.doc', 'r', encoding='UTF-8')
+ww = open('scripts/junk', "w")
+
+for line in rr:
+    if (line == " *   C O N V E N T I O N S   E T   R È G L E S   D E   N O M M A G E  -  2 0 2 4\n"):
+        print(line)
+        ww.write(line)
+
+rr.close()
+ww.close()
+
diff --git a/scripts/let_us_read_this_file.py b/scripts/let_us_read_this_file.py
new file mode 100755
index 0000000..9d14764
--- /dev/null
+++ b/scripts/let_us_read_this_file.py
@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+
+filename = 'read_me.doc'
+f = open(filename, 'r', encoding='UTF-8')
+
+print("Contenu de " + filename)
+print('-' * 30)
+for line in f:
+    print(line, end='')
+
+f.close()
+
+# 'with' est une solution plus simple, qui gère automatiquement la fermeture du fichier.
+filename = 'read_me.doc'
+
+print("\n\nContenu de " + filename)
+print('-' * 30)
+with open(filename, 'r', encoding='UTF-8') as f:
+    for line in f:
+        print(line, end='')
diff --git a/scripts/parsing_functions_names b/scripts/parsing_functions_names
new file mode 100644
index 0000000..f945165
--- /dev/null
+++ b/scripts/parsing_functions_names
@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+
+filename = 'read_me.doc'
+f = open(filename, 'r', encoding='UTF-8')
+
+# print("Contenu de " + filename) print('-' * 30)
+for line in f:
+    print(line, end='')
+
+f.close()
+
diff --git a/scripts/parsing_functions_names.py b/scripts/parsing_functions_names.py
new file mode 100755
index 0000000..f945165
--- /dev/null
+++ b/scripts/parsing_functions_names.py
@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+
+filename = 'read_me.doc'
+f = open(filename, 'r', encoding='UTF-8')
+
+# print("Contenu de " + filename) print('-' * 30)
+for line in f:
+    print(line, end='')
+
+f.close()
+