Code Monkey home page Code Monkey logo

qgis-documentation's Introduction

HTML Build Doctest Build Read the documentation

This repository is meant to write and manage the Official Documentation of QGIS, a free and Open Source Geographic Information System (GIS) Software, under the Open Source Geospatial (OSGeo) foundation umbrella.

The latest documentation is available at https://docs.qgis.org/latest

Building the documentation

  1. If not provided by your OS, you need to install:

    You can install both in default places and with default options.

  2. Clone the repository

  3. Go into that directory and follow the next instructions depending on your OS.

The best way to build the documentation is within a Python Virtual Environment (venv).

Build on Linux

To check/create the venv and use it in the build:

make -f venv.mk html

The venv.mk will create/update a virtual env (if not available) in current dir/venv AND run the html build in it.

You can also use that virtual environment later doing:

source venv/bin/activate

to activate the venv and then run the build from within that venv:

make html

If, for some reason, you want to start from scratch:

make -f venv.mk cleanall

Build on macOS or Linux

You can also use your own virtual env by creating it first:

# you NEED python >3.6. Depending on distro either use `python3` or `python`
# common name is 'venv' but call it whatever you like

python3 -m venv venv  # using the venv module, create a venv named 'venv'

Then activate the venv:

source ./venv/bin/activate

With 'activated' virtualenv, you should see 'venv' in the prompt. Install the requirements via the REQUIREMENTS.txt:

pip install -r REQUIREMENTS.txt

And run the build from within that venv:

make html

Want to build your own language? Note that you will use the translations from the po files from git! For example for 'nl' do:

make LANG=nl html

Build on Windows

Create a virtual environment called 'venv' in that directory (search the Internet for Python Virtual Env on Windows for more details), but in short: use the module 'venv' to create a virtual environment called 'venv'

# in dos box:
python -m venv venv

Then activate the venv:

venv\Scripts\activate.bat

With 'activated' virtualenv, you should see 'venv' in the prompt. Install the requirements via the REQUIREMENTS.txt:

pip install -r REQUIREMENTS.txt

And run the build from within that venv, using the make.bat script with the html argument to locally build the docs:

make.bat html

Want to build your own language? Note that you will use the translations from the po files from git! For example 'nl' do:

set SPHINXOPTS=-D language=nl
make.bat html

Build PDFs

In Linux, you can also build the PDF versions of the main documents.

make -f venv.mk pdf

Or after you enabled the venv:

make pdf

For building PDFs you will need to install the XeLaTex compiler package textlive-xetex and GNU Freefont.

sudo apt install textlive-xetex fonts-freefont

If you want to build PDFs in a language other than English, you can use a similar syntax:

make LANG=fr pdf

For building translated PDFs, you may have to install the texlive extra package for your specific language (e.g. texlive-lang-french). For japanese, it's crucial to install texlive-lang-japanese, which will install the platex compiler. If you plan to build all languages, it might be easier to install all languages packages (texlive-lang-all), but it will use a considerable amount of disk space.

Some languages will also need specific fonts installed:

  • Korea (ko) - NanumMyeongjo from the fonts-nanum package
  • Hindi (hi) - Nakula from the fonts-nakula package

Translating

http://www.sphinx-doc.org/en/master/usage/advanced/intl.html

https://pypi.org/project/sphinx-intl/

https://docs.transifex.com/integrations/transifex-github-integration

To update the english po files (which are being used as SOURCE files in transifex):

# FIRST create the pot files in build/gettext (po file be based on those pot files)
make gettext
# then update the english po files only:
sphinx-intl update -p build/gettext -l en

To create the .tx/config file to push/pull using tx client do:

# Creating the txconfig is only to be done the first time (we have one now...)
#sphinx-intl create-txconfig

# Update list of resources (necessary when files were added or removed)
sphinx-intl update-txconfig-resources --transifex-project-name qgis-documentation

# Then (only Transifex admin) can push the po source files to Transifex
tx push -fs --no-interactive #push the source (-s) files forcing (-f) overwriting the ones there without asking (--no-interactive)

To update all po files of all languages (Which we do not use here! This is done by Transifex):

export SPHINXINTL_LANGUAGE=de,nl, ...
# is the same same as
sphinx-intl <command> --language=de --language=nl ...

We created a script to create the transifex yaml files for github-transifex integrations.

BUT we do not do this yet as there were some technical issues...

.\scripts\create_transifex_yaml.sh

qgis-documentation's People

Contributors

alexbruy avatar anitagraser avatar benoitdm-oslandia avatar capooti avatar dassau avatar delazj avatar diethard2 avatar digro avatar dragons8mycat avatar elpaso avatar ghtmtt avatar havatv avatar jean-roc avatar junek avatar lajunek avatar m-kuhn avatar mach0 avatar mariesilvestre avatar pblottiere avatar pcav avatar rduivenvoorde avatar rosaguilar avatar srnetochan avatar timlinux avatar troopa81 avatar tudorbarascu avatar volaya avatar yjacolin avatar yjacolin-bot avatar yoichigmf avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.