Changes between Version 1 and Version 2 of building_the_docs


Ignore:
Timestamp:
28 Dec 2017, 11:44:05 (6 years ago)
Author:
bakaniko
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • building_the_docs

    v1 v2  
    2626== Required softwares ==
    2727
    28 * CMake (>= 2.8)
     28* CMake (>= 2.8)
    2929* git
    3030* perl:
    3131** 1 hour tutorial: https://www.youtube.com/watch?v=WEghIXs8F6c
    32 * sphinx (>=1.1)
     32* sphinx (>=1.1)
    3333
    3434=== Installing dependencies ===
    3535
    36 On <code>ubuntu 16.04</code>
     36On {{{ubuntu 16.04}}}
    3737
    3838<source lang="bash">sudo apt install cmake git
    … …  
    6363make html
    6464</source>
    65 And you're done ! You can go to <code>build/doc/_build/</code> and open <code>index.html</code> in a web browser.
     65And you're done ! You can go to {{{build/doc/_build/}}} and open {{{index.html}}} in a web browser.
    6666
    6767=== Main workflow ===
    6868
    69 * make the build directory <code>mkdir build</code>
    70 * get into build/: <code>cd build/</code>
     69* make the build directory {{{mkdir build}}}
     70* get into build/: {{{cd build/}}}
    7171
    7272==== Prepare the build with CMake ====
    7373
    74 With <code>cmake -D&lt;build option&gt;=ON  ..</code> with the option in uppercase:
    75 
    76 <code>cmake -DSINGLEHTML=ON  ..</code>
     74With {{{cmake -D<build option>=ON  ..}}} with the option in uppercase:
     75
     76{{{cmake -DSINGLEHTML=ON  ..}}}
    7777
    7878==== Available options ====
    … …  
    8080Available options can be see with the command:
    8181
    82 <code>cmake -L ..</code>
     82{{{cmake -L ..}}}
    8383
    8484===== Building options =====
    … …  
    9898As for now the supported languages are:
    9999
    100 * &quot;ca&quot;
    101 * &quot;de&quot;
    102 * &quot;es&quot;
    103 * &quot;fr&quot;
    104 * &quot;it&quot;
    105 * &quot;ja&quot;
    106 * &quot;ko&quot;
    107 * &quot;pl&quot;
    108 * &quot;ru&quot;
    109 * &quot;hu&quot;, &quot;el&quot;, &quot;id&quot; and &quot;zh&quot; are not available yet (bug fixe in progress)
    110 
    111 By default, english will be always made. You can add languages easily with the flag <code>-D&lt;Language code&gt;=ON</code>
     100* "ca"
     101* "de"
     102* "es"
     103* "fr"
     104* "it"
     105* "ja"
     106* "ko"
     107* "pl"
     108* "ru"
     109* "hu", "el", "id" and "zh" are not available yet (bug fixe in progress)
     110
     111By default, english will be always made. You can add languages easily with the flag {{{-D<Language code>=ON}}}
    112112
    113113For example, to get spanish:
    114114
    115 <code>cmake -DHTML=ON -DES=ON</code>
    116 
    117 To use a specific language, use the cmake flag <code>-D&lt;language code in uppercase&gt;=ON -D&lt;another language code in uppercase&gt;=ON</code>
     115{{{cmake -DHTML=ON -DES=ON}}}
     116
     117To use a specific language, use the cmake flag {{{-D<language code in uppercase>=ON -D<another language code in uppercase>=ON}}}
    118118
    119119You can pass no language flag (building only english) or as many flag as there is supported languages (and built all of them).
    120120
    121 To build all languages you can use the flag <code>-DALL_LANG=ON</code>
    122 
    123 The option (<code>-DES=ON ...</code> or <code>-DALL_LANG=ON</code>) are kept in the <code>OSGeoLiveDoc_BUILD_LANGUAGES</code> variable, which is automatically filled by CMake.
     121To build all languages you can use the flag {{{-DALL_LANG=ON}}}
     122
     123The option ({{{-DES=ON ...}}} or {{{-DALL_LANG=ON}}}) are kept in the {{{OSGeoLiveDoc_BUILD_LANGUAGES}}} variable, which is automatically filled by CMake.
    124124
    125125==== make the build ====
    126126
    127 <code>make &lt;option&gt;</code> with option in lowercase:
    128 
    129 <code>make singlehtml</code>
     127{{{make <option>}}} with option in lowercase:
     128
     129{{{make singlehtml}}}
    130130
    131131==== about Sphinx ====
    … …  
    133133Sphinx generates the po files used by transifex.
    134134
    135 Sphinx needs locales, english is set by default. Other locales are generated from the languages in <code>OSGeoLiveDoc_SUPPORTED_LANGUAGES</code> variable in <code>CMakeLists.txt</code>. For more details, see above.
     135Sphinx needs locales, english is set by default. Other locales are generated from the languages in {{{OSGeoLiveDoc_SUPPORTED_LANGUAGES}}} variable in {{{CMakeLists.txt}}}. For more details, see above.
    136136
    137137== Projects management ==
    138138
    139 Projects are loaded from the <code>projects_info.csv</code> file. It is the main entry point.
     139Projects are loaded from the {{{projects_info.csv}}} file. It is the main entry point.
    140140
    141141<blockquote>Note: Actually, it is manually build from this file: https://docs.google.com/spreadsheets/d/1Dem6RYkokaX61N8VcomebtqZvcUP-OOt14jt6GPL2TY/edit#gid=2122109332
    … …  
    145145Please indicate if there is a quickstart or not, an overview or not, an openHub account or not, the version, if it is an OSGeo project, or community or none of those.
    146146
    147 Overviews will be generated with the data from <code>projects_info.csv</code>, and links to quickstarts will be added automaticly.
     147Overviews will be generated with the data from {{{projects_info.csv}}}, and links to quickstarts will be added automaticly.
    148148
    149149More information how CMake use this file are available above.
    … …  
    153153There is 2 versions: regular and verbose.
    154154
    155 The first one can be called with this flag: <code>-DOSGeoLiveDoc_DEBUG=ON</code>
    156 
    157 For example: <code>cmake -DHTML=ON -DES=ON -DOSGeoLiveDoc_DEBUG=ON ..</code>
    158 
    159 The verbose debug is called with this flag: <code>-DOSGeoLiveDoc_VERBOSE_DEBUG=ON</code>
    160 
    161 For example: <code>cmake -DHTML=ON -DES=ON -DOSGeoLiveDoc_VERBOSE_DEBUG=ON ..</code>
     155The first one can be called with this flag: {{{-DOSGeoLiveDoc_DEBUG=ON}}}
     156
     157For example: {{{cmake -DHTML=ON -DES=ON -DOSGeoLiveDoc_DEBUG=ON ..}}}
     158
     159The verbose debug is called with this flag: {{{-DOSGeoLiveDoc_VERBOSE_DEBUG=ON}}}
     160
     161For example: {{{cmake -DHTML=ON -DES=ON -DOSGeoLiveDoc_VERBOSE_DEBUG=ON ..}}}
    162162
    163163== Configuring CMake / Setting the build ==
    164164
    165 CMake is use to build the repository instead of simply make because it can be finely tuned. CMake configuration is done by the <code>CMakeLists.txt</code>. CMake says how the build is made from that file.
     165CMake is use to build the repository instead of simply make because it can be finely tuned. CMake configuration is done by the {{{CMakeLists.txt}}}. CMake says how the build is made from that file.
    166166
    167167This file allows to set a few things:
    … …  
    169169==== Checking CMake version ====
    170170
    171 <code>cmake_minimum_required(VERSION 2.8 FATAL_ERROR)</code>
     171{{{cmake_minimum_required(VERSION 2.8 FATAL_ERROR)}}}
    172172
    173173==== Checking build folder ====
    174174
    175 The first thing that CMake does is to check if you are in the folder called <code>build</code>. If it is not the case, CMake will return an error.
     175The first thing that CMake does is to check if you are in the folder called {{{build}}}. If it is not the case, CMake will return an error.
    176176
    177177<pre class="{bash}">if ( ${CMAKE_SOURCE_DIR} STREQUAL ${CMAKE_BINARY_DIR} )
    178 message(FATAL_ERROR &quot;In-source builds not allowed.
     178message(FATAL_ERROR "In-source builds not allowed.
    179179Please make a new directory (called a build directory) and run CMake from there.
    180 You may need to remove CMakeCache.txt.&quot; )
     180You may need to remove CMakeCache.txt." )
    181181endif()</pre>
    182182==== Changing the version number ====
    183183
    184 In <code>CMakeLists.txt</code>, you can change the OSGeo-Live version number with the following variables:
     184In {{{CMakeLists.txt}}}, you can change the OSGeo-Live version number with the following variables:
    185185
    186186<pre class="{bash}">## Major version
    187 set(OSGeoLiveDoc_VERSION_MAJOR &quot;12&quot;)
     187set(OSGeoLiveDoc_VERSION_MAJOR "12")
    188188
    189189## minor version
    190 set(OSGeoLiveDoc_VERSION_MINOR &quot;0&quot;)
     190set(OSGeoLiveDoc_VERSION_MINOR "0")
    191191
    192192## Patch number
    193 set(OSGeoLiveDoc_VERSION_PATCH &quot;0&quot;)
     193set(OSGeoLiveDoc_VERSION_PATCH "0")
    194194
    195195## if it is a development version, a Release Candidate or a final release
    196 set(OSGeoLiveDoc_VERSION_DEV &quot;-dev&quot;)</pre>
     196set(OSGeoLiveDoc_VERSION_DEV "-dev")</pre>
    197197==== Checking the sphinx version ====
    198198
    199199To build, you sphinx 1.1 and above:
    200200
    201 <code>set(SPHINX_MINIMUM_VERSION &quot;1.1&quot;)</code>
     201{{{set(SPHINX_MINIMUM_VERSION "1.1")}}}
    202202
    203203If not a warning will be displayed. If you need a more recent version to build the doc, you can test it from here.
    … …  
    212212
    213213<source lang="bash">set(OSGeoLiveDoc_SUPPORTED_LANGUAGES "ca"  "de"  "es"  "fr"  "it"  "ja"  "ko"  "pl"  "ru")</source>
    214 Then add a new <code>INSERT_INTO_MAP</code> command to add the language to the lang navigation bar (in <code>index.html</code>). For example:
    215 
    216 <code>INSERT_INTO_MAP(&quot;fr&quot; &quot;Français&quot;)</code> in the <code>CMakeLists.txt</code>.
    217 
    218 The line <code>set(OSGeoLiveDoc_ENGLISH &quot;en&quot;)</code> is not supposed to change, it sets the default build in english.
     214Then add a new {{{INSERT_INTO_MAP}}} command to add the language to the lang navigation bar (in {{{index.html}}}). For example:
     215
     216{{{INSERT_INTO_MAP("fr" "Français")}}} in the {{{CMakeLists.txt}}}.
     217
     218The line {{{set(OSGeoLiveDoc_ENGLISH "en")}}} is not supposed to change, it sets the default build in english.
    219219
    220220=== Projects management ===
    221221
    222 Projects are loaded from the <code>projects_info.csv</code> file. It is the main entry point.
     222Projects are loaded from the {{{projects_info.csv}}} file. It is the main entry point.
    223223
    224224<blockquote>Note: Actually, it is manually build from this file: https://docs.google.com/spreadsheets/d/1Dem6RYkokaX61N8VcomebtqZvcUP-OOt14jt6GPL2TY/edit#gid=2122109332
    … …  
    228228Please indicate there is a quickstart or not, an overview or not, an openHub account or not, the version, if it is an OSGeo project, or community or none of those.
    229229
    230 Overviews will be generated with the data from <code>projects_info.csv</code>, and links to quickstarts will be added automaticly.
     230Overviews will be generated with the data from {{{projects_info.csv}}}, and links to quickstarts will be added automaticly.
    231231
    232232== reading the file ==
    233233
    234 <code>file(STRINGS projects_info.csv OSGeoLiveDoc_PROJECTS_VERSIONS_FILE)</code> opens the csv file
    235 
    236 <code>set (OSGeoLiveDoc_PROJECTS_VERSIONS &quot;&quot;)</code> is prepared to stock data from the file
     234{{{file(STRINGS projects_info.csv OSGeoLiveDoc_PROJECTS_VERSIONS_FILE)}}} opens the csv file
     235
     236{{{set (OSGeoLiveDoc_PROJECTS_VERSIONS "")}}} is prepared to stock data from the file
    237237
    238238Data are extracted with a regular expression, which detect the column, but has to know the number of columns. Currently the file has 9 columns.
    … …  
    242242== Slicing the lines with a regex ==
    243243
    244 <code>set (OSGeoLiveDoc_CONFIGURATION_REGEXP &quot;^(.*)\\|(.*)\\|(.*)\\|(.*)\\|(.*)\\|(.*)\\|(.*)\\|(.*)\\|(.*)&quot;)</code>
    245 
    246 So <code>(.*)\\|</code> has to be repeated 9 times. If a column is added in projects_info.csv, it is mandatory to add one more <code>(.*)\\|</code> in the regex to find the new column.
    247 
    248 Each column will extracted by group, for example, column 3 will be extracted as group &quot;\3&quot;; because it's a csv, it's kind of a 1 to 1 relationship between the group and the column.
     244{{{set (OSGeoLiveDoc_CONFIGURATION_REGEXP "^(.*)\\|(.*)\\|(.*)\\|(.*)\\|(.*)\\|(.*)\\|(.*)\\|(.*)\\|(.*)")}}}
     245
     246So {{{(.*)\\|}}} has to be repeated 9 times. If a column is added in projects_info.csv, it is mandatory to add one more {{{(.*)\\|}}} in the regex to find the new column.
     247
     248Each column will extracted by group, for example, column 3 will be extracted as group "\3"; because it's a csv, it's kind of a 1 to 1 relationship between the group and the column.
    249249
    250250Quick explanation of the regex:
    251251
    252 ^ &lt;--- beginning of line (.'') &lt;---- any character = &quot;.&quot; any number of times = &quot;''&quot; grouped &quot;(&quot; &quot;)&quot; \| &lt;--- code for vertical line &quot;|&quot;
    253 
    254 The for each line in the file, the ones starting with '''#''' are treated as comments. Comments will be ignored and the whole line replaced by a <code>#</code>.
     252^ <--- beginning of line (.'') <---- any character = "." any number of times = "''" grouped "(" ")" \| <--- code for vertical line "|"
     253
     254The for each line in the file, the ones starting with '''#''' are treated as comments. Comments will be ignored and the whole line replaced by a {{{#}}}.
    255255
    256256This part only use the 5 first column.
    … …  
    258258== Group use ==
    259259
    260 For example, group &quot;\3&quot;, will get the project version, and will be cleaned with <code>STRIP</code>:
    261 
    262 <code>string(STRIP ${project_version} project_version)</code> will strip the blanks spaces at the beginning and the end of the string. So &quot; 4.2.1 &quot; will return &quot;4.2.1&quot; and &quot;4.2.2 beta &quot; -&gt; &quot;4.2.2 beta&quot;.
     260For example, group "\3", will get the project version, and will be cleaned with {{{STRIP}}}:
     261
     262{{{string(STRIP ${project_version} project_version)}}} will strip the blanks spaces at the beginning and the end of the string. So " 4.2.1 " will return "4.2.1" and "4.2.2 beta " -> "4.2.2 beta".
    263263
    264264=== Debugging ===
    265265
    266 This treatment can be seen with the <code>-DOSGeoLiveDoc_VERBOSE_DEBUG=ON</code> flag. It will show something like that:
     266This treatment can be seen with the {{{-DOSGeoLiveDoc_VERBOSE_DEBUG=ON}}} flag. It will show something like that:
    267267
    268268-- Y 52nSOS 4.4.0 want_quickstart:Y want_overview:Y -- Y 52nWPS 3.6.1 want_quickstart:Y want_overview:Y -- N 52nWSS retired want_quickstart:N want_overview:N -- 52nWSS is not for documentation -- N atlasstyler retired want_quickstart:N want_overview:N -- atlasstyler is not for documentation -- N cartaro retired want_quickstart:N want_overview:N -- cartaro is not for documentation
    … …  
    270270Active projects will get want_quickstart and want_overview set to Y; the retired projects will be set to N and won't be used for documentation.
    271271
    272 This process is always done, but won't be print unless the <code>-DOSGeoLiveDoc_VERBOSE_DEBUG=ON</code> flag is used.
     272This process is always done, but won't be print unless the {{{-DOSGeoLiveDoc_VERBOSE_DEBUG=ON}}} flag is used.
    273273
    274274=== Project version in conf.py ===
    … …  
    276276For each line (so active and retired projects), a new python command will be generated for inserting in conf.py.
    277277
    278 <code>.. |version-${project_name}| replace:: ${project_version}\n&quot;</code>
    279 
    280 For example, for the ''4.4.0'' release of the ''52nSOS'' project, the string will be <code>.. |version-52nSOS| replace:: 4.4.0</code>.
     278{{{.. |version-${project_name}| replace:: ${project_version}\n"}}}
     279
     280For example, for the ''4.4.0'' release of the ''52nSOS'' project, the string will be {{{.. |version-52nSOS| replace:: 4.4.0}}}.
    281281
    282282=== Selecting project who needs on overview and a quickstart building ===
    … …  
    284284This code add the project name to lists for quickstart and overviews, if a Y is the columns/ groups 4 and 5. Some projects might have an overview but no quickstart, it is mostly libraries.
    285285
    286 if (&quot;<math>{want_quickstart}" MATCHES "Y") list(APPEND OSGeoLiveDoc_QUICKSTART "</math>{project_name}&quot;) endif() if (&quot;<math>{want_overview}" MATCHES "Y") list(APPEND OSGeoLiveDoc_OVERVIEW "</math>{project_name}&quot;) endif()
     286if ("<math>{want_quickstart}" MATCHES "Y") list(APPEND OSGeoLiveDoc_QUICKSTART "</math>{project_name}") endif() if ("<math>{want_overview}" MATCHES "Y") list(APPEND OSGeoLiveDoc_OVERVIEW "</math>{project_name}") endif()
    287287
    288288= Standards =
    … …  
    290290Standards are builded with this set of commandes:
    291291
    292 set(OSGeoLiveDoc_STANDARDS &quot;csw&quot; &quot;gml&quot; &quot;sld&quot; &quot;wcs&quot; &quot;wms&quot; &quot;fe&quot; &quot;kml&quot; &quot;sensorml&quot; &quot;sos&quot; &quot;wfs&quot; &quot;wps&quot; ) # Other settings There is several files that is need for the build, they are copied with the command <code>configure_file()</code>
     292set(OSGeoLiveDoc_STANDARDS "csw" "gml" "sld" "wcs" "wms" "fe" "kml" "sensorml" "sos" "wfs" "wps" ) # Other settings There is several files that is need for the build, they are copied with the command {{{configure_file()}}}
    293293
    294294* settings.py
    … …  
    297297* translators.csv
    298298
    299 For example, <code>configure_file(&quot;settings.py&quot; &quot;settings.py&quot;)</code> will copy ''settings.py'' and '''substitute''' the variables defined in the cmake. Which is very handy.
     299For example, {{{configure_file("settings.py" "settings.py")}}} will copy ''settings.py'' and '''substitute''' the variables defined in the cmake. Which is very handy.
    300300
    301301The csv files are copied but are not modified. They'll be loaded later in the html file with an another process.
    … …  
    303303= Setting building variables =
    304304
    305 The line <code>add_subdirectory(doc)</code> will add the '''doc''' folder to the build and all the files in it will be set with the variables from cmake, by copying the CMakeLists.txt file in each folder and subfolder. Each copy
     305The line {{{add_subdirectory(doc)}}} will add the '''doc''' folder to the build and all the files in it will be set with the variables from cmake, by copying the CMakeLists.txt file in each folder and subfolder. Each copy
    306306
    307307= Comments in CMake =
    … …  
    313313= Included files and folder =
    314314
    315 CMake will use the files and folders in the main folder (aka <code>OSGeoLive-doc</code>) but only the ones present in the variables <code>OSGeoLiveDoc_FILES</code> and <code>OSGeoLiveDoc_FOLDERS</code>.
     315CMake will use the files and folders in the main folder (aka {{{OSGeoLive-doc}}}) but only the ones present in the variables {{{OSGeoLiveDoc_FILES}}} and {{{OSGeoLiveDoc_FOLDERS}}}.
    316316
    317317In CMakeLists.txt they are set like that:
    … …  
    321321#---------------------
    322322set(OSGeoLiveDoc_FILES
    323 #&quot;disclaimer.rst&quot;
    324 &quot;translators.rst&quot;
    325 &quot;osgeo_contact.rst&quot;
    326 &quot;contributors.rst&quot;
    327 &quot;index.rst&quot;
    328 &quot;contact.rst&quot;
    329 #&quot;metrics.rst&quot;
    330 &quot;sponsors.rst&quot;
    331 &quot;welcome_message.txt&quot;
    332 &quot;copyright.rst&quot;
    333 &quot;download.rst&quot;
    334 &quot;mac_installers.rst&quot;
    335 &quot;presentation.rst&quot;
    336 &quot;sponsors_osgeo.rst&quot;
    337 &quot;prior_applications.rst&quot;
    338 &quot;win_installers.rst&quot;
     323#"disclaimer.rst"
     324"translators.rst"
     325"osgeo_contact.rst"
     326"contributors.rst"
     327"index.rst"
     328"contact.rst"
     329#"metrics.rst"
     330"sponsors.rst"
     331"welcome_message.txt"
     332"copyright.rst"
     333"download.rst"
     334"mac_installers.rst"
     335"presentation.rst"
     336"sponsors_osgeo.rst"
     337"prior_applications.rst"
     338"win_installers.rst"
    339339)
    340340
    … …  
    344344#---------------------
    345345set(OSGeoLiveDoc_SUBDIRS
    346 &quot;WindowsInstallers&quot;
    347 &quot;MacInstallers&quot;
    348 &quot;presentation&quot;
    349 &quot;quickstart&quot;
    350 &quot;overview&quot;
    351 &quot;standards&quot;
     346"WindowsInstallers"
     347"MacInstallers"
     348"presentation"
     349"quickstart"
     350"overview"
     351"standards"
    352352)</pre>
    353 So commented out or deleted lines won't be taken in account, and won't be translated. If you comment &quot;overview&quot;, the overviews won't be built.
     353So commented out or deleted lines won't be taken in account, and won't be translated. If you comment "overview", the overviews won't be built.
    354354
    355355= Directory processing =
    356356
    357 This process is managed by the command <code>add_subdirectory()</code> which tell '''CMake''' to look for a ''CMakeLists.txt'' in the subdirectory and execute it.
    358 
    359 For example, the last line of the main ''CMakeLists.txt'' is <code>add_subdirectory(doc)</code> so '''CMake''' will look into doc/ and execute the ''CMakeLists.txt'' in it. Several variables will be initialized like <code>${OSGeoLiveDoc_SUBDIRS}</code> which contains the folders to look into.
     357This process is managed by the command {{{add_subdirectory()}}} which tell '''CMake''' to look for a ''CMakeLists.txt'' in the subdirectory and execute it.
     358
     359For example, the last line of the main ''CMakeLists.txt'' is {{{add_subdirectory(doc)}}} so '''CMake''' will look into doc/ and execute the ''CMakeLists.txt'' in it. Several variables will be initialized like {{{${OSGeoLiveDoc_SUBDIRS}}}} which contains the folders to look into.
    360360
    361361Then the following loop will be looking in each named subfolder to execute its ''CMakeLists.txt''
    362362
    363 <code>{bash} foreach (dir ${OSGeoLiveDoc_SUBDIRS}) message(STATUS &quot;   Adding directory ${dir}&quot;) add_subdirectory(${dir}) endforeach()</code>
    364 
    365 For example, the proccessed files for the Overview folder are extract from <code>${OSGeoLiveDoc_OVERVIEW})</code> built in the previous process (from <code>projects_info.csv</code>). Files not listed in <code>${OSGeoLiveDoc_OVERVIEW})</code> won't be processed.
     363{{{{bash} foreach (dir ${OSGeoLiveDoc_SUBDIRS}) message(STATUS "   Adding directory ${dir}") add_subdirectory(${dir}) endforeach()}}}
     364
     365For example, the proccessed files for the Overview folder are extract from {{{${OSGeoLiveDoc_OVERVIEW})}}} built in the previous process (from {{{projects_info.csv}}}). Files not listed in {{{${OSGeoLiveDoc_OVERVIEW})}}} won't be processed.
    366366
    367367== Local list ==
    … …  
    375375== Quickstart and Overview folder ==
    376376
    377 The CMakeLists.txt here to copy all projects listed in <code>projetc_info.csv</code> and transmitted with the variables <code>${OSGeoLiveDoc_QUICKSTART}</code> and <code>${OSGeoLiveDoc_OVERVIEW}</code>.
     377The CMakeLists.txt here to copy all projects listed in {{{projetc_info.csv}}} and transmitted with the variables {{{${OSGeoLiveDoc_QUICKSTART}}}} and {{{${OSGeoLiveDoc_OVERVIEW}}}}.
    378378
    379379Local CMakeLists.txt will be initialized with those variables.
    … …  
    381381=== Overview folder ===
    382382
    383 in Overview, there is no local files. The Overview webpage (listing all projects) is generated with perl from data extracted of <code>projects_info.csv</code>.
     383in Overview, there is no local files. The Overview webpage (listing all projects) is generated with perl from data extracted of {{{projects_info.csv}}}.
    384384
    385385== Standards ==
    … …  
    389389== Main files ==
    390390
    391 Main files, present at the root of the project and website, are processed if listed in the variable <code>OSGeoLiveDoc_FILES</code> at the beginning of the ''CMakeLists.txt''. They can be added and commented out easily.
     391Main files, present at the root of the project and website, are processed if listed in the variable {{{OSGeoLiveDoc_FILES}}} at the beginning of the ''CMakeLists.txt''. They can be added and commented out easily.
    392392
    393393= Images =
    394394
    395 The images folder is entirely copied to <code>build/doc/images</code>. All images are copied, even the one that are not used by the documentation any more. That need to be cleaned.
     395The images folder is entirely copied to {{{build/doc/images}}}. All images are copied, even the one that are not used by the documentation any more. That need to be cleaned.
    396396
    397397= Scripts =
    398398
    399 Some files are build with perl scripts like <code>overview.html</code> or <code>metrics</code>. Those scripts will be detailed below.
     399Some files are build with perl scripts like {{{overview.html}}} or {{{metrics}}}. Those scripts will be detailed below.
    400400
    401401== overview.html ==
    402402
    403 [https://live.osgeo.org/en/overview/overview.html overview.html] is the overview of all projects, and is generated from data in <code>projects_info.csv</code>. So retired project wouldn't appear in it.
     403[https://live.osgeo.org/en/overview/overview.html overview.html] is the overview of all projects, and is generated from data in {{{projects_info.csv}}}. So retired project wouldn't appear in it.
    404404
    405405The script is there: https://github.com/cvvergara/OSGeoLive-doc/blob/cm_fix_header/doc/scripts/build_overview.pl
    … …  
    407407First three lines are testing the shell and args.
    408408
    409 There is includes (<code>pragmas</code>) from perl library used by the script in line 6 to 8.
     409There is includes ({{{pragmas}}}) from perl library used by the script in line 6 to 8.
    410410
    411411Then three specials variables are declared: - ''name (filename) - ''dir (get the directory of the perl script) - *prune (get the path to the perl script)
    412412
    413 They are shortcuts for functions (<code>*File::Find::name</code> is a function returning the filename).
    414 
    415 Those varaibles are loaded with informations from the CMake: * <code>$DEBUG = &quot;@OSGeoLiveDoc_DEBUG@&quot;;</code> * <code>$version = &quot;@OSGeoLiveDoc_VERSION@&quot;;</code> * <code>$projects_info_file = '@CMAKE_SOURCE_DIR@/projects_info.csv';</code> * <code>$output_file = '@CMAKE_BINARY_DIR@/doc/overview/overview.rst';</code>
    416 
    417 ==== See if the <code>projects_info.csv</code> file exist, if don't the script stop and throws an error: ====
    418 
    419 <code>die &quot;ERROR: Failed to find: '$projects_info_file'\n&quot; unless -f $projects_info_file;</code>
     413They are shortcuts for functions ({{{*File::Find::name}}} is a function returning the filename).
     414
     415Those varaibles are loaded with informations from the CMake: * {{{$DEBUG = "@OSGeoLiveDoc_DEBUG@";}}} * {{{$version = "@OSGeoLiveDoc_VERSION@";}}} * {{{$projects_info_file = '@CMAKE_SOURCE_DIR@/projects_info.csv';}}} * {{{$output_file = '@CMAKE_BINARY_DIR@/doc/overview/overview.rst';}}}
     416
     417==== See if the {{{projects_info.csv}}} file exist, if don't the script stop and throws an error: ====
     418
     419{{{die "ERROR: Failed to find: '$projects_info_file'\n" unless -f $projects_info_file;}}}
    420420
    421421=== Get the configuration from projects_info.csv ===
    422422
    423 This line parse the projects_info file and stores it in <code>$configuration</code>. If the flag <code>-DOSGeoLiveDoc_DEBUG=ON</code> is used, then a comment line will be print.
     423This line parse the projects_info file and stores it in {{{$configuration}}}. If the flag {{{-DOSGeoLiveDoc_DEBUG=ON}}} is used, then a comment line will be print.
    424424
    425425<source lang="perl">my $configuration = read_and_parse_configuration($projects_info_file);</source>
    426426==== read_and_parse_configuration subroutine ====
    427427
    428 This subroutine takes a file in parameter. It is stored in $file with the keyword <code>shift</code>.
     428This subroutine takes a file in parameter. It is stored in $file with the keyword {{{shift}}}.
    429429
    430430Then an empty Hash called %hash is initialized. It will store hashes extracted during the process.
    … …  
    432432The script will try to open the file in parameter or die and throws an error.
    433433
    434 Then a while loop reads the file line by line and exit when the file is empty (operation becomes <code>TRUE</code>). During the while loop several actions are made: - ignores the commented lines; - clean the line by removing spaces surplus; - ignores project who are not subject to documentation (no overview and / or no quickstart) - get lines in the right bucket (section) <code>$hash{$values[5]}</code>
     434Then a while loop reads the file line by line and exit when the file is empty (operation becomes {{{TRUE}}}). During the while loop several actions are made: - ignores the commented lines; - clean the line by removing spaces surplus; - ignores project who are not subject to documentation (no overview and / or no quickstart) - get lines in the right bucket (section) {{{$hash{$values[5]}}}}
    435435
    436436For example, with the following line:
    437437
    438 <code>Y | 52nSOS | 4.4.0 | Y | Y | Web Services | | Sensor Observation Service | SensorObservationService</code>
     438{{{Y | 52nSOS | 4.4.0 | Y | Y | Web Services | | Sensor Observation Service | SensorObservationService}}}
    439439
    440440The instructions will put the line in the bucket that has the name ''Web Services''.
    … …  
    442442At the end of the loop, the file is closed and the hash with the collected data is returned.
    443443
    444 In the script, the hash will be store in <code>$configuration</code>.
     444In the script, the hash will be store in {{{$configuration}}}.
    445445
    446446=== Building sections ===
    447447
    448 Sections are stored in <code>$sections</code>.
    449 
    450 For each defined sections, there will be a call for the section in <code>$configuration</code>. It use the subroutine <code>get_section</code>.
    451 
    452 The result will be append to <code>$sections</code>.
     448Sections are stored in {{{$sections}}}.
     449
     450For each defined sections, there will be a call for the section in {{{$configuration}}}. It use the subroutine {{{get_section}}}.
     451
     452The result will be append to {{{$sections}}}.
    453453
    454454==== get_sections() ====
    … …  
    456456This subroutine take two parameters: * the name of the section * the variable where the configuration is stored
    457457
    458 <blockquote>Note: There is a lot of concatenation in this subroutine. It is short written with <code>.=</code>
     458<blockquote>Note: There is a lot of concatenation in this subroutine. It is short written with {{{.=}}}
    459459</blockquote>
    460 get_sections() workflow: - prepare the section headers and toc tree - split values around the <code>|</code>and store it in an array (@values) - cleans the excess <code>|</code> and spaces in in each value - Test it ''overview'' is set to <code>Y</code> then handle the overview by adding it to the toctree and adding the bullet line - Test it ''quickstart'' is set to <code>Y</code> then handle the quickstart by adding it to the toctree and adding the bullet line between brackets - Write the comment / short description if provided.
     460get_sections() workflow: - prepare the section headers and toc tree - split values around the {{{|}}}and store it in an array (@values) - cleans the excess {{{|}}} and spaces in in each value - Test it ''overview'' is set to {{{Y}}} then handle the overview by adding it to the toctree and adding the bullet line - Test it ''quickstart'' is set to {{{Y}}} then handle the quickstart by adding it to the toctree and adding the bullet line between brackets - Write the comment / short description if provided.
    461461
    462462When all projects have been read, the toctree is added to the contents, then the bullets. The contents is returned.
    … …  
    464464=== Writing the file ===
    465465
    466 When all the sections are build and added to <code>$sections</code>, the subroutine <code>write_script()</code> is called.
    467 
    468 It takes one parameter, <code>$sections</code> with all the sections, in the right order.
     466When all the sections are build and added to {{{$sections}}}, the subroutine {{{write_script()}}} is called.
     467
     468It takes one parameter, {{{$sections}}} with all the sections, in the right order.
    469469
    470470# it tries to create the output file (or die if cannot)
    471471# write out the header and the commands to clean up the old extension
    472 # paste the content of <code>$sections</code> after the toc (<code>.. contents:\n :local:</code>) and before prior applications
     472# paste the content of {{{$sections}}} after the toc ({{{.. contents:\n :local:}}}) and before prior applications
    473473# close the file
    474474
    475475== Script exit ==
    476476
    477 When the script is done, it exit returning <code>0</code>. It is a mandatory for perl.
     477When the script is done, it exit returning {{{0}}}. It is a mandatory for perl.
    478478
    479479= Metrics.pl =
    … …  
    481481=== Variables ===
    482482
    483 The variables are loaded by CMake during the build from data in <code>CMakeLists.txt</code>.
     483The variables are loaded by CMake during the build from data in {{{CMakeLists.txt}}}.
    484484
    485485<source lang="perl">my $DEBUG = "@OSGeoLiveDoc_DEBUG@";
    … …  
    501501To do that, we will use a one liner perl command to change from projects/gvsigFOOOOOOOOOOOO to projects/gvsig
    502502
    503 the <code>/</code> is special in perl so, <code>\</code> is prepended in the command from projects/gvsigFOOOOOOOOOOOO to projects/gvsig
     503the {{{/}}} is special in perl so, {{{\}}} is prepended in the command from projects/gvsigFOOOOOOOOOOOO to projects/gvsig
    504504
    505505==== THE command: ====
    506506
    507507<source lang="bash">perl -pi -e "s/projects\/gvsigFOOOOOOOOOOOO/projects\/gvsig/" $(git ls-files)</source>
    508 * <code>git ls-files</code> : lists the files that git knows about
    509 * <code>perl</code> &lt;--- use that
    510 * <code>-pi</code> &lt;--- one liner
    511 * <code>-e</code> &lt;-- do changes on the file and save them on the file
    512 * &quot;s/projects/gvsigFOOOOOOOOOOOO/projects/gvsig/&quot; &lt;&lt;&lt; s/<from>/<to>/ substitute from to
    513 * <code>$(git ls-files)</code> &lt;---- $(<command>)
    514 * <code>git ls-files</code> &lt;--- generates filenames know to git
     508* {{{git ls-files}}} : lists the files that git knows about
     509* {{{perl}}} <--- use that
     510* {{{-pi}}} <--- one liner
     511* {{{-e}}} <-- do changes on the file and save them on the file
     512* "s/projects/gvsigFOOOOOOOOOOOO/projects/gvsig/" <<< s/<from>/<to>/ substitute from to
     513* {{{$(git ls-files)}}} <---- $(<command>)
     514* {{{git ls-files}}} <--- generates filenames know to git
    515515
    516516= Check and remove unused images =
    … …  
    526526= Theming =
    527527
    528 Themes are stock in the <code>_theme</code> subdirectory, they are loaded by the line [https://github.com/cvvergara/OSGeoLive-doc/blob/cm_fix_header/doc/CMakeLists.txt#L79 L. 79 of CMakeLists.txt]
     528Themes are stock in the {{{_theme}}} subdirectory, they are loaded by the line [https://github.com/cvvergara/OSGeoLive-doc/blob/cm_fix_header/doc/CMakeLists.txt#L79 L. 79 of CMakeLists.txt]
    529529
    530530There is a small [https://github.com/cvvergara/OSGeoLive-doc/blob/cm_fix_header/doc/_themes/overview/CMakeLists.txt local CMakeLists.txt] for each theme. It is used to configure the language bar with the asked languages.