add a named label for every example and FAQ item

_unittests/ut_helpgen/test_small_functions.py

@@ -0,0 +1,29 @@
+"""
+@brief      test log(time=8s)
+@author     Xavier Dupre
+"""
+
+import sys, os, unittest, shutil
+
+
+try :
+    import src
+except ImportError :
+    path =  os.path.normpath(os.path.abspath(os.path.join(os.path.split(__file__)[0], "..", "..")))
+    if path not in sys.path : sys.path.append(path)
+    import src
+
+from src.pyquickhelper.loghelper.flog           import fLOG
+from src.pyquickhelper.helpgen.utils_sphinx_doc_helpers import make_label_index
+
+class TestSmallFunction(unittest.TestCase):
+
+    def test_make_label_index(self) :
+        fLOG (__file__, self._testMethodName, OutputPrint = __name__ == "__main__")
+        title = "abAB_-()56$?"
+        res = make_label_index(title,"")
+        fLOG("***",title,res)
+        assert res == "abAB_-56"
+
+if __name__ == "__main__"  :
+    unittest.main ()    

src/pyquickhelper/helpgen/utils_sphinx_doc.py

@@ -9,7 +9,9 @@
 from ..loghelper.flog           import fLOG
 from ..sync.synchelper          import remove_folder, synchronize_folder, explore_folder
 from ._my_doxypy                import process_string
-from .utils_sphinx_doc_helpers  import add_file_rst_template, process_var_tag, import_module, get_module_objects, add_file_rst_template_cor, add_file_rst_template_title, IndexInformation, RstFileHelp, HelpGenException, process_look_for_tag
+from .utils_sphinx_doc_helpers  import add_file_rst_template, process_var_tag, import_module
+from .utils_sphinx_doc_helpers  import get_module_objects, add_file_rst_template_cor, add_file_rst_template_title
+from .utils_sphinx_doc_helpers  import IndexInformation, RstFileHelp, HelpGenException, process_look_for_tag, make_label_index
 from ..pandashelper.tblformat   import df_to_rst
 
 def validate_file_for_help(filename, fexclude = lambda f : False) :
@@ -1308,7 +1310,8 @@ def private_migrating_doxygen_doc(
                 fil     = os.path.splitext(os.path.split(filename)[-1])[0]
                 fil     = re.sub(r'([^a-zA-Z0-9_])', "", fil)
                 ref     = fil + "-l%d" % (i+index_first_line)
-                to      = "\n\n%s.. _le-%s:\n\n%s**Example: %s**  \n\n%s.. example(%s%s;;le-%s)." % (sp,ref,sp,exa,sp,pag,exa,ref)
+                ref2    = make_label_index(exa, str(example.groups()))
+                to      = "\n\n%s.. _le-%s:\n\n%s.. _le-%s:\n\n%s**Example: %s**  \n\n%s.. example(%s%s;;le-%s)." % (sp,ref,sp,ref2,sp,exa,sp,pag,exa,ref)
                 rows[i] = row.replace(rep, to)
 
                 # it requires an empty line before if the previous line does not start by :
@@ -1325,7 +1328,8 @@ def private_migrating_doxygen_doc(
                 fil     = os.path.splitext(os.path.split(filename)[-1])[0]
                 fil     = re.sub(r'([^a-zA-Z0-9_])', "", fil)
                 ref     = fil + "-l%d" % (i+index_first_line)
-                to      = "\n\n%s.. _le-%s:\n\n%s**FAQ: %s**  \n\n%s.. FAQ(%s%s;;le-%s)." % (sp,ref,sp,exa,sp,pag,exa,ref)
+                ref2    = make_label_index(exa, str(faq.groups()))
+                to      = "\n\n%s.. _le-%s:\n\n%s.. _le-%s:\n\n%s**FAQ: %s**  \n\n%s.. FAQ(%s%s;;le-%s)." % (sp,ref,sp,ref2,sp,exa,sp,pag,exa,ref)
                 rows[i] = row.replace(rep, to)
 
                 # it requires an empty line before if the previous line does not start by :

src/pyquickhelper/helpgen/utils_sphinx_doc_helpers.py

@@ -611,7 +611,31 @@ def process_var_tag(docstring, rst_replace = False, header = ["attribute", "mean
                 for a in alls :
                     values.append ( a )
         return values
-
+
+def make_label_index(title, comment):
+    """
+    build a sphinx label from a string by
+    removing any odd characters
+    
+    @param      title       title
+    @param      comment     add this string in the exception when it raises one
+    @return                 label
+    """
+    def accept(c):
+        if "a" <= c <= "z" : return c
+        if "A" <= c <= "Z" : return c
+        if "0" <= c <= "9" : return c
+        if c in "-_" : return c
+        return ""
+
+    try:
+        r = "".join( map (accept, title) )
+        if len(r) == 0:
+            raise HelpGenException("unable to interpret this title (empty?): {0} (type: {2})\nCOMMENT:\n{1}".format(str(title), comment, str(type(title)))) 
+        return r
+    except TypeError as e :
+        raise HelpGenException("unable to interpret this title: {0} (type: {2})\nCOMMENT:\n{1}".format(str(title), comment, str(type(title)))) from e
+
 def process_look_for_tag(tag, title, files):
     """
     looks for specific information in all files, collect them
@@ -694,6 +718,10 @@ def noneempty(a):
         for pa, a,b,c in coll :
             pan = re.sub(r'([^a-zA-Z0-9_])', "", pa)
             if page != pan : continue
+            lindex = make_label_index( a, pan )
+            rows.append( "" )
+            rows.append( ".. _lm-{0}:".format( lindex ) )
+            rows.append( "" )
             rows.append( a )
             rows.append( "+" * len(a) )
             rows.append( "" )

src/pyquickhelper/serverdoc/documentation_server.py

@@ -433,7 +433,7 @@ def run_doc_server (server,
     @param      port        port to use
     @return                 server if thread is False, the thread otherwise (the thread is started)
     
-    @example("run a local server which serves the documentation")
+    @example(run a local server which serves the documentation)
     
     The following code will create a local server: `http://localhost:8079/pyquickhelper/ <http://localhost:8079/pyquickhelper/>`_.
     @code