__TOC__ Here put examples on how to build the docs Logs of documentation writing: * Building the docs: ** http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-07-27.log ** http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-07-28.log * http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-07-31.log * http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-08-09.log * http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-08-10.log * http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-08-16.log * http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-08-17.log * generating overview: ** http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-08-24.log * Fixing issues: ** http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-09-05.log * Conf.py and locales (1/2): ** http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-09-06.log * locales (2/2) * next time * sphinx commands / transifex ** http://irclogs.geoapt.com/osgeolive/%23osgeolive.2017-09-13.log == Required softwares == * CMake (>= 2.8) * git * perl: ** 1 hour tutorial: https://www.youtube.com/watch?v=WEghIXs8F6c * sphinx (>=1.1) === Installing dependencies === On {{{ubuntu 16.04}}} {{{ sudo apt install cmake git sudo -H pip install sphinx }}} == Preparing the repository == === cloning the repository === This is a temporary repository before merging into the main one {{{ git clone https://github.com/cvvergara/OSGeoLive-doc }}} === branching === {{{ git checkout develop }}} === Python 2.7 === This builds works with python 2.7. If it is not standard into your environnement, create a virtual one. This is an example with the anaconda distribution. {{{ conda create -n docbuild27 python=2.7 anaconda source activate docbuild27 }}} To exit the environnement at the end: {{{ source deactivate }}} == Build commands == === Simplest build === This build will only make the English version and will be faster so you can quickly visualize your changes. {{{ ## making the build folder (where builds will be put) mkdir build ## Getting into the build directory cd build # Preparing the build cmake -DHTML=ON .. # don't forget the .. at the end !! # Build html files make html }}} And you're done ! You can go to {{{~/OSGeoLive-doc/build/doc/_build/html}}} and open {{{index.html}}} in a web browser. === Main workflow === * make the build directory {{{mkdir build}}} * get into build/: {{{cd build/}}} ==== Prepare the build with CMake ==== With {{{cmake -D=ON ..}}} with the option in uppercase: {{{cmake -DSINGLEHTML=ON ..}}} ==== Available options ==== Available options can be see with the command: {{{cmake -L ..}}} ===== Building options ===== There is several option available to the build: * HTML (plain HTML) * DIRHTML (HTML pages with internal links not working) * SINGLEHTML (All the docs in a single html page) * PICKLE * JSON * HTMLHELP * LATEX (LaTeX format, used to generate pdfs) ===== Languages options ===== As for now the supported languages are: * "ca" * "de" * "es" * "fr" * "it" * "ja" * "ko" * "pl" * "ru" * "hu", "el", "id" and "zh" are not available yet (bug fixe in progress) By default, english will be always made. You can add languages easily with the flag {{{-D=ON}}} For example, to get spanish: {{{cmake -DHTML=ON -DES=ON}}} To use a specific language, use the cmake flag {{{-D=ON -D=ON}}} You can pass no language flag (building only english) or as many flag as there is supported languages (and built all of them). To build all languages you can use the flag {{{-DALL_LANG=ON}}} The option ({{{-DES=ON ...}}} or {{{-DALL_LANG=ON}}}) are kept in the {{{OSGeoLiveDoc_BUILD_LANGUAGES}}} variable, which is automatically filled by CMake. ==== make the build ==== {{{make