Changeset 8


Ignore:
Timestamp:
10/02/15 20:20:33 (8 years ago)
Author:
pinsard
Message:

simplification of procedure for checking typo (no more rst, no more python, only HTML from wiki)

Location:
trunk/docs/manual
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/docs/manual/for_typo/people.txt

    r4 r8  
    1111Céline 
    1212Déandreis 
     13Denvil 
    1314esci 
    1415Fairhead 
  • trunk/docs/manual/source/conf.py

    r7 r8  
    128128# The theme to use for HTML and HTML Help pages.  See the documentation for 
    129129# a list of builtin themes. 
    130 html_theme = 'alabaster' 
     130html_theme = 'sphinxdoc' 
    131131 
    132132# Theme options are theme-specific and customize the look and feel of a theme 
  • trunk/docs/manual/source/developers/guides/requirements.rst

    r7 r8  
    3030   - :command:`xdg-open` vs  :command:`open` 
    3131   - python distribution 
     32   - locale setup (ie values of :envvar:`LC` and associates) 
    3233 
    33 Download the repository some where on ciclad: 
     34Download the repository : 
    3435 
    3536.. code-block:: bash 
     
    3738   PROJECT=${HOME}/igcmg_doc_ws  # ${HOME}/igcmg_doc_ws is an example 
    3839   export PROJECT 
    39    svn checkout svn+ssh://<YOURLOGIN>@forge.ipsl.jussieu.fr/ipsl/forge/projets/igcmg_doc/svn/trunk ${PROJECT} 
     40   loginforge=yourlogin  # login on forge.ipsl.jussieu.fr 
     41   svn checkout svn+ssh://${loginforge}@forge.ipsl.jussieu.fr/ipsl/forge/projets/igcmg_doc/svn/trunk ${PROJECT} 
    4042 
    4143Environment 
     
    6062   pip install --upgrade sphinxcontrib-blockdiag 
    6163   source deactivate 
     64 
     65.. todo:: explain why 
    6266 
    6367.. todo:: explain how to update 
     
    103107   PROJECT_LOG=${HOME}/log/ 
    104108   export PROJECT_LOG 
     109   mkdir ${PROJECT_LOG} # only once 
  • trunk/docs/manual/source/developers/guides/typo.rst

    r7 r8  
    77Typo may be hard to find in all sources (code, documentation, tools) files. 
    88 
    9 Both :command:`pylint` and :command:`hunspell` help to detect those mistakes. 
     9:command:`hunspell` help to detect those mistakes. 
     10 
     11:command:`pylint` can also be used for Python source. 
    1012 
    1113They use dictionaries providing natural langages list of words. 
     
    1517.. blockdiag:: typo_blockdiag.dot 
    1618 
    17 Missing words in dictionaries 
    18 ============================= 
     19Missing words in dictionaries by categories 
     20=========================================== 
    1921 
    20 They lack some scientific words (ex barocline), computer langages reserved 
    21 words, acronyms (ex. IGCMG) and code variables names. 
     22System dictionaries lack some scientific words (ex barocline), 
     23computer langages reserved words, acronyms (ex. IGCMG) and 
     24code variables names. 
    2225 
    2326Those missing words can be listed in specific files. 
     
    3134:command:`hunspell`. 
    3235 
    33 Python variables dictionary 
    34 +++++++++++++++++++++++++++ 
    35  
    36 .. note:: 
    37  
    38    this work was done in PAGO project. not yet useful here 
    39  
    40 :py:mod:`prog_var_francoise.py` is a way to build the dictionary "python 
    41 variables". 
    42  
    43 .. code-block:: bash 
    44  
    45    prog_var_francoise.py ${PROJECT} --outfile ${PROJECT_LOG}/pyigcmg_doc_var.txt 
    46  
    47 shell scripts variables dictionary 
    48 ++++++++++++++++++++++++++++++++++ 
    49  
    50 .. todo:: 
    51  
    52    find a way to scan shell scripts files to extract variables. 
    53    may by with pygmentize ... 
    54  
    5536Build one supplemental dictionary 
    5637+++++++++++++++++++++++++++++++++ 
    5738 
    5839Supplemental dictionaries can be joined in one and be added to the list of 
    59 dictionaries used in an spelling check of all :file:`*.py` via :command:`pylint`. 
    60  
    61 They also will be the base of the one used by :command:`hunspell`. 
     40dictionaries used in an spelling check of via :command:`hunspell`. 
    6241 
    6342They must be encoded in UTF-8. 
     
    7352      cat ${onefile} >> ${nontypo} 
    7453   done 
    75    cat ${PROJECT_LOG}/pyigcmg_doc_var.txt >> ${nontypo} 
    7654   sort -u ${nontypo} > ${nontypo_uniq} 
    7755 
    78 .. note:: 
    79  
    80    no ${PROJECT_LOG}/pyigcmg_doc_var.txt here 
    81  
    82 Check typo in Python files 
    83 ========================== 
    84  
    85 .. code-block:: bash 
    86  
    87    listf=$(find ${PROJECT} -name "*.py") 
    88    pylint --disable=all \ 
    89    --enable=spelling \ 
    90    --spelling-dict=en_US \ 
    91    --spelling-private-dict-file=${nontypo_uniq} \ 
    92    --reports=n \ 
    93    ${listf} | grep "Wrong spelling" | awk -F: '{print $3}' | \ 
    94    sort -u > ${PROJECT_LOG}/typo 
    95  
    96 .. todo:: 
    97  
    98    or add in a pylint resource file in a :samp:`spelling-private-dict-file=` line 
    99  
    100 To find one of the wrong spelling: 
    101  
    102 .. code-block:: bash 
    103  
    104    w=blanck 
    105    find ${PROJECT} -name "*.py" -exec grep -Hi ${w} {} \; 
    106  
    107 Files can be fixed or one of the supplemental dictionaries completed. 
    108  
    109 Check typo in non Python files 
    110 ============================== 
    111  
    112 The dictionary can also be used to check for typo in documentation files 
    113 (:file:`*.rst`) 
    114  
    115 .. tip:: 
    116  
    117    To see the path of existing default dictionaries of :command:`hunspell` : 
    118  
    119    .. code-block:: bash 
    120  
    121       hunspell -D 
    122  
    123 .. todo:: 
    124  
    125    not only rst files 
     56The list ${nontypo_uniq} can also be used to check for typo in 
     57documentation files and source code. 
    12658 
    12759First alter the list of variable to produce a :file:`.dic` file 
     
    13567   sed "1i ${linecount}" ${nontypo_uniq} > ${nontypo_uniq_dic} 
    13668 
    137 Associated :file:`nontypo_uniq.aff` file already exist in 
    138 ${PROJECT}/docs/manual/for_typo: 
    139  
    140 Now we have :file:`${PROJECT_LOG}/nontypo_uniq.dic` and 
    141 :file:`pyigcmg_doc_var.aff` usable for :command:`hunspell`. 
     69Associated :file:`nontypo_uniq.aff` file already exists in 
     70:file:`${PROJECT}/docs/manual/for_typo`: 
    14271 
    14372.. code-block:: bash 
     
    14574   ln -s ${PROJECT}/docs/manual/for_typo/nontypo_uniq.aff ${PROJECT_LOG}/nontypo_uniq.aff 
    14675 
    147 .. code-block:: bash 
     76Now we have :file:`${PROJECT_LOG}/nontypo_uniq.dic` and 
     77:file:`${PROJECT_LOG}/nontypo_uniq.aff` usable for :command:`hunspell`. 
    14878 
    149    cd ${PROJECT_LOG} 
    150    listf=$(find $PROJECT -name "*.rst") 
    151    hunspell_out=${PROJECT_LOG}/hunspell_out 
    152    hunspell_uniq_out=${PROJECT_LOG}/hunspell_uniq_out 
    153    rm -f ${hunspell_out}  ${hunspell_uniq_out} 
    154    for onefile in ${listf} 
    155    do 
    156       hunspell -d en_US,nontypo_uniq --check-url -i utf-8 -l < ${onefile} >> ${hunspell_out} 
    157    done 
    158    sort -u ${hunspell_out} > ${hunspell_uniq_out} 
     79Check typo in files 
     80=================== 
    15981 
    16082.. todo:: 
     
    16385   ${PROJECT_LOG} where .dic and .aff files are located. 
    16486 
    165 In :file:`${hunspell_uniq_out}`, all unknown words are listed. 
    166  
    167 To find one of the wrong spelling: 
    168  
    169 .. code-block:: bash 
    170  
    171    w=amonch 
    172    find ${PROJECT} -name "*.rst" -exec grep -Hi ${w} {} \; 
    173  
    174 Once all corrected, remove :file:`${hunspell_uniq_out}` and 
    175 :file:`${hunspell_uniq}`. 
    176  
    17787Check typo in wiki pages 
    17888++++++++++++++++++++++++ 
    17989 
    18090Until :ref:`tracwiki_migration` is not achieved, we have to check typo in 
    181 HTML files produced by trac on the `<http://forge.ipsl.jussieu.fr/igcmg_doc/wiki/>`_ 
     91HTML files produced by trac on the 
     92`<http://forge.ipsl.jussieu.fr/igcmg_doc/wiki/>`_ 
    18293 
    18394By convention, it has been decided to start all |igcmg_doc| pages names by ``Doc``. 
     
    190101   list_uri=$(xsltproc \-\-novalid \ 
    191102   ${PROJECT}/docs/manual/for_tracwiki/titleindex.xsl http://forge.ipsl.jussieu.fr/igcmg_doc/wiki/TitleIndex | \ 
    192    grep "/igcmg_doc/wiki/Doc" | grep -v ${excluded_uri} |sort -u | \ 
     103   grep "/igcmg_doc/wiki/Doc" | grep -v ${excluded_uri} | sort -u | \ 
    193104   sed -e "s@^@http://forge.ipsl.jussieu.fr/@") 
    194105 
     
    217128   for onefile in ${listf} 
    218129   do 
    219       hunspell -d en_US,nontypo_uniq --check-url -i utf-8 -l < ${onefile} >> ${hunspell_out} 
     130      LANG=POSIX;hunspell -d en_US,nontypo_uniq --check-url -i utf-8 -l < ${onefile} >> ${hunspell_out} 
    220131   done 
    221132   sort -u ${hunspell_out} > ${hunspell_uniq_out} 
     133 
     134.. warning:: 
     135 
     136   side effect of LANG=POSIX; 
     137   how to avoid LANG change after execution execution 
     138 
     139:file:`${hunspell_uniq_out}` contains : 
     140 
     141- typo to be fixed in wiki pages 
     142- false positif to be added in a :file:`docs/manual/for_typo/` 
     143- false positif to be ignored because to hard to add (encoding issue for 
     144  Greek word, etc.) 
     145 
     146.. warning:: 
     147 
     148   The following command print only lines present in both ${hunspell_uniq_out} ${nontypo_uniq}. 
     149 
     150   .. code-block :: bash 
     151 
     152      comm -12 ${hunspell_uniq_out} ${nontypo_uniq} 
     153 
     154   If not empty, the supplemental dictionary has not being used by :command:`hunspell` 
     155 
     156.. todo:: 
     157 
     158   give some ideas (LC, ?) 
    222159 
    223160To find one of the wrong spelling in downloaded HTML pages: 
     
    225162.. code-block:: bash 
    226163 
    227    w=amonch 
     164   w=amonch # take a real one from ${hunspell_uniq_out} 
    228165   find ${dirhtml} -name "Doc*" -exec grep -Hi ${w} {} \; 
    229166 
    230 .. warning: 
     167.. note:: 
     168 
     169   It is also possible to find wrong spelling via the search facility 
     170   on the trac interface but resultats may differ (case sensitivity, 
     171   trac plugins) 
     172 
     173.. warning:: 
    231174 
    232175   Correction have to be done via the wiki interface of the forge. 
Note: See TracChangeset for help on using the changeset viewer.