Fixes #196, add rst links in docstrings

_unittests/ut_text/test_text_code_helper.py

@@ -22,8 +22,7 @@
         sys.path.append(path)
     import src
 
-from src.pyquickhelper.loghelper import fLOG
-from src.pyquickhelper.texthelper import change_style
+from src.pyquickhelper.texthelper import change_style, add_rst_links
 
 
 class TestTextCodeHelper(unittest.TestCase):
@@ -33,14 +32,18 @@ def test_src_import(self):
         self.assertTrue(src is not None)
 
     def test_change_style(self):
-        fLOG(
-            __file__,
-            self._testMethodName,
-            OutputPrint=__name__ == "__main__")
         self.assertEqual(change_style("changeStyle"), "change_style")
         self.assertEqual(change_style("change_Style"), "change__style")
         self.assertEqual(change_style("change_style"), "change_style")
 
+    def test_add_rst_links(self):
+        text = "Maybe... Python is winning the competition\nfor machine learning language."
+        values = {'Python': 'https://www.python.org/',
+                  'machine learning': 'https://en.wikipedia.org/wiki/Machine_learning'}
+        res = add_rst_links(text, values)
+        exp = "Maybe... :epkg:`Python` is winning the competition\nfor :epkg:`machine learning` language."
+        self.assertEqual(exp, res)
+
 
 if __name__ == "__main__":
     unittest.main()

src/pyquickhelper/helpgen/sphinxm_convert_doc_sphinx_helper.py

@@ -61,7 +61,8 @@
     try:
         from sphinx.extension import verify_required_extensions as verify_extensions
     except ImportError as ee:
-        raise ImportError("Unable to import sphinx due to:\n{0}\n{1}".format(e, ee))
+        raise ImportError(
+            "Unable to import sphinx due to:\n{0}\n{1}".format(e, ee))
 
 try:
     from sphinx.writers.latex import LaTeXTranslator

src/pyquickhelper/texthelper/__init__.py

@@ -3,7 +3,7 @@
 @brief shortcuts to text
 """
 
-from .code_helper import change_style
+from .code_helper import change_style, add_rst_links
 from .diacritic_helper import remove_diacritics
 from .templating import CustomTemplateException, apply_template
 from .version_helper import compare_module_version

src/pyquickhelper/texthelper/code_helper.py

@@ -16,10 +16,51 @@ def change_style(name):
 
     Example:
 
-    ::
+    .. runpython::
+        :showcode:
 
-        changeStyle --> change__style
+        from pyquickhelper.texthelper import change_style
+
+        print("changeStyle --> {0}".format(change_style('change_style')))
     """
     s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
     s2 = re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
     return s2 if not keyword.iskeyword(s2) else s2 + "_"
+
+
+def add_rst_links(text, values, tag="epkg", n=4):
+    """
+    Replaces words by something like ``:epkg:'word'``.
+
+    @param      text        text to process
+    @param      values      values
+    @param      tag         tag to use
+    @param      n           number of consecutive words to look at
+    @return                 new text
+
+    .. runpython::
+        :showcode:
+
+        from pyquickhelper.texthelper import add_rst_links
+        text = "Maybe... Python is winning the competition for machine learning language."
+        values = {'Python': 'https://www.python.org/',
+                  'machine learning': 'https://en.wikipedia.org/wiki/Machine_learning'}
+        print(add_rst_links(text, values))
+    """
+    def replace(words, i, n):
+        mx = max(len(words), i + n)
+        for last in range(mx, i, -1):
+            w = ''.join(words[i:last])
+            if w in values:
+                return last, ":{0}:`{1}`".format(tag, w)
+        return i + 1, words[i]
+
+    reg = re.compile("(([\\w']+)|([.,!?;]+)|([ \\n]+))")
+    words = reg.findall(text)
+    words = [_[0] for _ in words]
+    res = []
+    i = 0
+    while i < len(words):
+        i, w = replace(words, i, n)
+        res.append(w)
+    return ''.join(res)