Changes between Version 9 and Version 10 of building_the_docs


Ignore:
Timestamp:
26 Aug 2018, 08:21:19 (6 years ago)
Author:
bakaniko
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • building_the_docs

    v9 v10  
    172172Projects are loaded from the {{{projects_info.csv}}} file. It is the main entry point.
    173173
     174  Note: Actually, it is manually build from this file: https://docs.google.com/spreadsheets/d/1Dem6RYkokaX61N8VcomebtqZvcUP-OOt14jt6GPL2TY/edit#gid=2122109332
     175
     176To add a project or update project version, modify the projects_csv file: https://github.com/<PATH TO FILE>/projects_info.csv
     177
     178Please 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.
     179
     180Overviews will be generated with the data from {{{projects_info.csv}}}, and links to quickstarts will be added automaticly.
     181
     182More information how CMake use this file are available above.
     183
     184== Debugging ==
     185
     186There is 2 versions: regular and verbose.
     187
     188The first one can be called with this flag: {{{-DOSGeoLiveDoc_DEBUG=ON}}}
     189
     190For example: {{{cmake -DHTML=ON -DES=ON -DOSGeoLiveDoc_DEBUG=ON ..}}}
     191
     192The verbose debug is called with this flag: {{{-DOSGeoLiveDoc_VERBOSE_DEBUG=ON}}}
     193
     194For example: {{{cmake -DHTML=ON -DES=ON -DOSGeoLiveDoc_VERBOSE_DEBUG=ON ..}}}
     195
     196== Configuring CMake / Setting the build ==
     197
     198CMake 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.
     199
     200This file allows to set a few things:
     201
     202==== Checking CMake version ====
     203
     204{{{cmake_minimum_required(VERSION 2.8 FATAL_ERROR)}}}
     205
     206==== Checking build folder ====
     207
     208The 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.
     209
     210{{{
     211if ( ${CMAKE_SOURCE_DIR} STREQUAL ${CMAKE_BINARY_DIR} )
     212message(FATAL_ERROR "In-source builds not allowed.
     213Please make a new directory (called a build directory) and run CMake from there.
     214You may need to remove CMakeCache.txt." )
     215endif()
     216}}}
     217
     218==== Changing the version number ====
     219
     220In {{{CMakeLists.txt}}}, you can change the OSGeo-Live version number with the following variables:
     221
     222{{{
     223## Major version
     224set(OSGeoLiveDoc_VERSION_MAJOR "12")
     225
     226## minor version
     227set(OSGeoLiveDoc_VERSION_MINOR "0")
     228
     229## Patch number
     230set(OSGeoLiveDoc_VERSION_PATCH "0")
     231
     232## if it is a development version, a Release Candidate or a final release
     233set(OSGeoLiveDoc_VERSION_DEV "-dev")
     234}}}
     235==== Checking the sphinx version ====
     236
     237To build, you sphinx 1.1 and above:
     238
     239{{{set(SPHINX_MINIMUM_VERSION "1.1")}}}
     240
     241If not a warning will be displayed. If you need a more recent version to build the doc, you can test it from here.
     242
     243==== Checking Perl ====
     244
     245Perl is needed at some point, so
     246
     247==== Adding / removing a language ====
     248
     249Add the 2 letters code of the new language:
     250
     251{{{set(OSGeoLiveDoc_SUPPORTED_LANGUAGES "ca"  "de"  "es"  "fr"  "it"  "ja"  "ko"  "pl"  "ru")}}}
     252Then add a new {{{INSERT_INTO_MAP}}} command to add the language to the lang navigation bar (in {{{index.html}}}). For example:
     253
     254{{{INSERT_INTO_MAP("fr" "Français")}}} in the {{{CMakeLists.txt}}}.
     255
     256The line {{{set(OSGeoLiveDoc_ENGLISH "en")}}} is not supposed to change, it sets the default build in english.
     257
     258=== Projects management ===
     259
     260Projects are loaded from the {{{projects_info.csv}}} file. It is the main entry point.
     261
    174262<blockquote>Note: Actually, it is manually build from this file: https://docs.google.com/spreadsheets/d/1Dem6RYkokaX61N8VcomebtqZvcUP-OOt14jt6GPL2TY/edit#gid=2122109332
    175263</blockquote>
    176264To add a project or update project version, modify the projects_csv file: https://github.com/<PATH TO FILE>/projects_info.csv
    177265
    178 Please 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.
     266Please 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.
    179267
    180268Overviews will be generated with the data from {{{projects_info.csv}}}, and links to quickstarts will be added automaticly.
    181269
    182 More information how CMake use this file are available above.
    183 
    184 == Debugging ==
    185 
    186 There is 2 versions: regular and verbose.
    187 
    188 The first one can be called with this flag: {{{-DOSGeoLiveDoc_DEBUG=ON}}}
    189 
    190 For example: {{{cmake -DHTML=ON -DES=ON -DOSGeoLiveDoc_DEBUG=ON ..}}}
    191 
    192 The verbose debug is called with this flag: {{{-DOSGeoLiveDoc_VERBOSE_DEBUG=ON}}}
    193 
    194 For example: {{{cmake -DHTML=ON -DES=ON -DOSGeoLiveDoc_VERBOSE_DEBUG=ON ..}}}
    195 
    196 == Configuring CMake / Setting the build ==
    197 
    198 CMake 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.
    199 
    200 This file allows to set a few things:
    201 
    202 ==== Checking CMake version ====
    203 
    204 {{{cmake_minimum_required(VERSION 2.8 FATAL_ERROR)}}}
    205 
    206 ==== Checking build folder ====
    207 
    208 The 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.
    209 
    210 {{{if ( ${CMAKE_SOURCE_DIR} STREQUAL ${CMAKE_BINARY_DIR} )
    211 message(FATAL_ERROR "In-source builds not allowed.
    212 Please make a new directory (called a build directory) and run CMake from there.
    213 You may need to remove CMakeCache.txt." )
    214 endif()}}}
    215 ==== Changing the version number ====
    216 
    217 In {{{CMakeLists.txt}}}, you can change the OSGeo-Live version number with the following variables:
    218 
    219 {{{## Major version
    220 set(OSGeoLiveDoc_VERSION_MAJOR "12")
    221 
    222 ## minor version
    223 set(OSGeoLiveDoc_VERSION_MINOR "0")
    224 
    225 ## Patch number
    226 set(OSGeoLiveDoc_VERSION_PATCH "0")
    227 
    228 ## if it is a development version, a Release Candidate or a final release
    229 set(OSGeoLiveDoc_VERSION_DEV "-dev")}}}
    230 ==== Checking the sphinx version ====
    231 
    232 To build, you sphinx 1.1 and above:
    233 
    234 {{{set(SPHINX_MINIMUM_VERSION "1.1")}}}
    235 
    236 If not a warning will be displayed. If you need a more recent version to build the doc, you can test it from here.
    237 
    238 ==== Checking Perl ====
    239 
    240 Perl is needed at some point, so
    241 
    242 ==== Adding / removing a language ====
    243 
    244 Add the 2 letters code of the new language:
    245 
    246 {{{set(OSGeoLiveDoc_SUPPORTED_LANGUAGES "ca"  "de"  "es"  "fr"  "it"  "ja"  "ko"  "pl"  "ru")}}}
    247 Then add a new {{{INSERT_INTO_MAP}}} command to add the language to the lang navigation bar (in {{{index.html}}}). For example:
    248 
    249 {{{INSERT_INTO_MAP("fr" "Français")}}} in the {{{CMakeLists.txt}}}.
    250 
    251 The line {{{set(OSGeoLiveDoc_ENGLISH "en")}}} is not supposed to change, it sets the default build in english.
    252 
    253 === Projects management ===
    254 
    255 Projects are loaded from the {{{projects_info.csv}}} file. It is the main entry point.
    256 
    257 <blockquote>Note: Actually, it is manually build from this file: https://docs.google.com/spreadsheets/d/1Dem6RYkokaX61N8VcomebtqZvcUP-OOt14jt6GPL2TY/edit#gid=2122109332
    258 </blockquote>
    259 To add a project or update project version, modify the projects_csv file: https://github.com/<PATH TO FILE>/projects_info.csv
    260 
    261 Please 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.
    262 
    263 Overviews will be generated with the data from {{{projects_info.csv}}}, and links to quickstarts will be added automaticly.
    264 
    265270== reading the file ==
    266271
    … …  
    309314For each line (so active and retired projects), a new python command will be generated for inserting in conf.py.
    310315
    311 {{{.. |version-${project_name}| replace:: ${project_version}\n"}}}
     316{{{
     317.. |version-${project_name}| replace:: ${project_version}\n"
     318}}}
    312319
    313320For example, for the ''4.4.0'' release of the ''52nSOS'' project, the string will be {{{.. |version-52nSOS| replace:: 4.4.0}}}.
    … …  
    317324This 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.
    318325
     326{{{
    319327if ("<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()
    320 
     328}}}
    321329= Standards =
    322330
    … …  
    342350There is no comments in CMake, but there is a way to have code that won't be executed.
    343351
     352{{{
    344353if(FALSE) <none executed code> endif()
     354}}}
    345355
    346356= Included files and folder =
    … …  
    350360In CMakeLists.txt they are set like that:
    351361
    352 {{{#---------------------
     362{{{
     363#---------------------
    353364# Files
    354365#---------------------
    … …  
    383394"overview"
    384395"standards"
    385 )}}}
     396)
     397}}}
     398
    386399So 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.
    387400
    … …  
    450463==== See if the {{{projects_info.csv}}} file exist, if don't the script stop and throws an error: ====
    451464
    452 {{{die "ERROR: Failed to find: '$projects_info_file'\n" unless -f $projects_info_file;}}}
     465{{{
     466die "ERROR: Failed to find: '$projects_info_file'\n" unless -f $projects_info_file;
     467}}}
    453468
    454469=== Get the configuration from projects_info.csv ===
    … …  
    456471This 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.
    457472
    458 {{{my $configuration = read_and_parse_configuration($projects_info_file);}}}
     473{{{
     474my $configuration = read_and_parse_configuration($projects_info_file);
     475}}}
     476
    459477==== read_and_parse_configuration subroutine ====
    460478
    … …  
    516534The variables are loaded by CMake during the build from data in {{{CMakeLists.txt}}}.
    517535
    518 {{{my $DEBUG = "@OSGeoLiveDoc_DEBUG@";
     536{{{
     537my $DEBUG = "@OSGeoLiveDoc_DEBUG@";
    519538my $version = "@OSGeoLiveDoc_VERSION@";
    520539my $projects_info_file = '@CMAKE_SOURCE_DIR@/projects_info.csv';
    521 my $output_file = '@CMAKE_CURRENT_BINARY_DIR@/../metrics.rst';}}}
     540my $output_file = '@CMAKE_CURRENT_BINARY_DIR@/../metrics.rst';
     541}}}
     542
    522543= Useful commands =
    523544
    … …  
    526547==== Moving the files to the right folder ====
    527548
    528 {{{git mv doc/images/projects/gvsigFOOOOOOOOOOOO doc/images/projects/gvsig
     549{{{
     550git mv doc/images/projects/gvsigFOOOOOOOOOOOO doc/images/projects/gvsig
    529551
    530552# see the change
    531 git status}}}
     553git status
     554}}}
    532555==== Changing all occurrences ====
    533556