From 1335cffab407d7671cf5722d9f6cbc7ada8d57dc Mon Sep 17 00:00:00 2001 From: Matthias Kuhn Date: Tue, 17 Nov 2015 13:34:31 +0100 Subject: [PATCH] Initial commit --- .gitignore | 6 + .travis.yml | 40 ++++ Makefile | 279 ++++++++++++++++++++++++++ en/index.rst | 29 +++ en/installation-guide/index.rst | 4 + en/project-management/index.rst | 12 ++ en/user-guide/index.rst | 7 + requirements.txt | 2 + scripts/build-docs.sh | 11 + scripts/ci/deploy-docs.sh | 26 +++ scripts/ci/setup_git.sh | 10 + scripts/create_transifex_resources.sh | 70 +++++++ 12 files changed, 496 insertions(+) create mode 100644 .gitignore create mode 100644 .travis.yml create mode 100644 Makefile create mode 100644 en/index.rst create mode 100644 en/installation-guide/index.rst create mode 100644 en/project-management/index.rst create mode 100644 en/user-guide/index.rst create mode 100644 requirements.txt create mode 100755 scripts/build-docs.sh create mode 100755 scripts/ci/deploy-docs.sh create mode 100755 scripts/ci/setup_git.sh create mode 100755 scripts/create_transifex_resources.sh diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..74974c51b --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +build +compile_messages +init +*~ +*.mo +i18n/pot diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 000000000..36a12eadd --- /dev/null +++ b/.travis.yml @@ -0,0 +1,40 @@ +language: python + +addons: + apt: + packages: + - texlive-latex-recommended + - texlive-latex-extra + - texlive-fonts-recommended + +notifications: + webhooks: + urls: + - https://webhooks.gitter.im/e/7d967d9679efbbc43466 + on_success: change # options: [always|never|change] default: always + on_failure: always # options: [always|never|change] default: always + on_start: false # default: false + +before_install: + - mkdir -p $HOME/texlive && curl -L https://github.com/urdh/texlive-blob/releases/download/20150712/texlive.tar.xz | tar -JxC $HOME/texlive + +install: +# Sphinx requirements + - pip install -r requirements.txt +# Latex requirements + - PATH=$HOME/texlive/bin/x86_64-linux:$PATH + - tlmgr update --self + - tlmgr install combelow + - tlmgr install babel-french + - tlmgr install babel-german + - tlmgr install babel-romanian + - tlmgr install babel-italian + +before_script: + - ./scripts/ci/setup_git.sh + +script: + - ./scripts/build-docs.sh + +after_success: + - ./scripts/ci/deploy-docs.sh diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..e0a5f8f62 --- /dev/null +++ b/Makefile @@ -0,0 +1,279 @@ +# Makefile for Sphinx documentation +# +# $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/$$lang; +# + +# You can set these variables from the command line. +BUILDDIR = build +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = a4 +SHELL = /bin/bash +TRANSLATIONS_STATIC = en +TRANSLATIONS_I18N = de fr it ro +LANGUAGES = $(TRANSLATIONS_STATIC) $(TRANSLATIONS_I18N) +BUILD_LANGUAGES = $(TRANSLATIONS_I18N) $(TRANSLATIONS_STATIC) + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees/$$lang $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -c . -A language=$$lang -D language=$$lang -A languages='$(LANGUAGES)' + +ALLSPHINXOPTSI18N = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -c . -a -A language=$$lang -D language=$$lang -A languages='$(LANGUAGES)' + +# Only for Gettext +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -c . -A language=en -D language=en -A languages='en' + +.PHONY: help clean html web pickle htmlhelp latex changes linkcheck + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " init to preprocess translation directories" + @echo " compile_messages to compile po to mo files" + @echo " generate_po_from_tmpl to duplicate pot to po files for a language, e.g from i18n\pot directory to i18n\lang" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " all-pdf to make PDF file" + @echo " all-ps to make PS file" + @echo " changes to make an overview over all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " gettext to generate pot files from en rst files" + @echo " gettext_copy to duplicate pot files from gettext dir to i18n\pot" + +clean: + -rm -rf $(BUILDDIR)/* init compile_messages + +clean-repo: clean + @set -e; for lang in $(TRANSLATIONS_STATIC) ;\ + do \ + for file in `find $$lang -type f -a -regex '.*\.*$$' -a -not -regex '.*\.$$' -a -not -regex '.*\.svn.*' -printf "%p\n" ; cd ..;`; \ + do \ + echo "Working on "$$file ; \ +# is file in git? \ + if [ ! -d "$$file" -a -n "`git status --porcelain $$file`" ]; then \ + rm -f "$$file"; \ +# is dir empty? \ + ldir=`dirname "$$file" `; \ + if [ ! -n "`ls -1 $$ldir`" ]; then \ + echo "Removing empty dir "$$ldir; \ + rm -rf "$$ldir"; \ + fi \ + fi \ + done ; \ + done + @echo "Clean-repo finished." + +init: en/* + @set -e; for lang in $(TRANSLATIONS_STATIC) ;\ + do \ + for file in `cd en; find . -type f -name '*.rst' ; cd ..;`; \ + do \ + if [ ! -f $$lang/$$file ]; then \ + mkdir -p `dirname "$$lang/$$file"`; \ + (echo ".. meta::"; echo " :ROBOTS: NOINDEX") | cat - "en/$$file" > "$$lang/$$file"; \ + fi \ + done; \ + for file in `cd en; find . -type f ; cd ..;`; \ + do \ + if [ ! -f $$lang/$$file ]; then \ + mkdir -p `dirname "$$lang/$$file"`; \ + cp -p "en/$$file" "$$lang/$$file"; \ + fi \ + done; \ + done + @echo "Init finished. Other target can now be built.";\ + touch init + +transifex_sync: gettext + @set -e;\ + ./scripts/create_transifex_resources.sh; \ + tx push -s; \ + tx pull + @echo "Transifex resources synchronized" + +compile_messages: init i18n/*/*.po + @set -e; for lang in $(TRANSLATIONS_I18N) ;\ + do \ + echo "Compiling messages for $$lang..."; \ + for f in `find ./i18n/$$lang -type f -name \*.po`; \ + do \ + bn=`basename $$f .po`; \ + echo "Compiling messages for $$f"; \ + mkdir -p ./i18n/$$lang/LC_MESSAGES; \ + msgfmt $$f -o ./i18n/$$lang/LC_MESSAGES/$$bn.mo; \ + done; \ + done + @echo "Messages compiled. Now you can build updated version for html and pdf.";\ + touch compile_messages + +html: compile_messages + @set -e; \ + lang=en; \ + mkdir -p $(BUILDDIR)/html $(BUILDDIR)/doctrees/$$lang; \ + echo $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/html; \ + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/html; \ + for lang in $(BUILD_LANGUAGES); \ + do \ + mkdir -p $(BUILDDIR)/html/$$lang $(BUILDDIR)/doctrees/$$lang; \ + if [[ "$(TRANSLATIONS_STATIC)" =~ "$$lang" ]]; then \ + mkdir -p $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/html/$$lang; \ + else \ + if [[ "$(TRANSLATIONS_I18N)" =~ "$$lang" ]]; then \ + $(SPHINXBUILD) -b html $(ALLSPHINXOPTSI18N) en build/html/$$lang; \ + fi \ + fi \ + done + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html/."; + +gettext: + mkdir -p $(BUILDDIR)/gettext/en $(BUILDDIR)/doctrees/en; \ + echo "$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) en $(BUILDDIR)/gettext/en";\ + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) en i18n/pot;\ + + @echo "Build finished. The pot files pages are in i18n/pot.";\ + +singlehtml: compile_messages + @set -e; for lang in en $(TRANSLATIONS_STATIC);\ + do \ + mkdir -p $(BUILDDIR)/singlehtml/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/singlehtml/$$lang;\ + done + @set -e; for lang in $(TRANSLATIONI18N);\ + do \ + mkdir -p $(BUILDDIR)/singlehtml/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTSI18N) en $(BUILDDIR)/singlehtml/$$lang;\ + done + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/singlehtml/.";\ + +pickle: compile_messages + @set -e; for lang in en $(TRANSLATIONS_STATIC);\ + do \ + mkdir -p $(BUILDDIR)/pickle/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/pickle/$$lang;\ + done + @set -e; for lang in $(TRANSLATIONI18N);\ + do \ + mkdir -p $(BUILDDIR)/pickle/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTSI18N) en $(BUILDDIR)/pickle/$$lang;\ + done + @echo + @echo "Build finished; now you can process the pickle files." + +web: pickle + +json: compile_messages + @set -e; for lang in en $(TRANSLATIONS_STATIC);\ + do \ + mkdir -p $(BUILDDIR)/json/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/json/$$lang;\ + done + @set -e; for lang in $(TRANSLATIONI18N);\ + do \ + mkdir -p $(BUILDDIR)/json/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b json $(ALLSPHINXOPTSI18N) en $(BUILDDIR)/json/$$lang;\ + done + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: compile_messages + @set -e; for lang in en $(TRANSLATIONS_STATIC);\ + do \ + mkdir -p $(BUILDDIR)/htmlhelp/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/htmlhelp/$$lang;\ + done + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp/." + +latex: compile_messages + @set -e; for lang in $(LANGUAGES);\ + do \ + mkdir -p $(BUILDDIR)/latex/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) en $(BUILDDIR)/latex/$$lang; \ + done + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex/." + @echo "Run \`make all-pdf' or \`make all-ps'" + +pdf: compile_messages + @set -e;\ + $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) en $(BUILDDIR)/pdf;\ + for lang in $(TRANSLATIONS_STATIC);\ + do \ + mkdir -p $(BUILDDIR)/pdf/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/pdf/$$lang;\ + done + @set -e; for lang in $(TRANSLATIONS_I18N);\ + do \ + mkdir -p $(BUILDDIR)/pdf/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b pdf $(ALLSPHINXOPTSI18N) en $(BUILDDIR)/pdf/$$lang;\ + done + @echo + @echo "Build finished; the PDF files are in $(BUILDDIR)/pdf/."\ + @echo "Run \`make pdf' " + +epub: compile_messages + @set -e; for lang in en;\ + do \ + mkdir -p $(BUILDDIR)/epub/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/epub/$$lang;\ + done + @echo + @echo "Build finished; the epub files are in $(BUILDDIR)/epub/."\ + @echo "Run \`make epub' " + +all-pdf: latex + @set -e; \ + for lang in $(LANGUAGES); \ + do \ + make -C $(BUILDDIR)/latex/$$lang all-pdf ; \ + if [ -d $(BUILDDIR)/html/$$lang ]; then \ + cp -f $(BUILDDIR)/latex/$$lang/QGEP.pdf $(BUILDDIR)/html/$$lang ; \ + fi \ + done; \ + if [ -d $(BUILDDIR)/html/$$lang ]; then \ + cp -f $(BUILDDIR)/latex/en/QGEP.pdf $(BUILDDIR)/html; \ + fi; \ + +all-ps: latex + @set -e; for lang in $(LANGUAGES);\ + do \ + make -C $(BUILDDIR)/latex/$$lang all-ps ; \ + done + +changes: + @for lang in $(LANGUAGES);\ + do \ + mkdir -p $(BUILDDIR)/changes/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/changes/$$lang;\ + done + @echo + @echo "The overview file is in $(BUILDDIR)/changes/." + +linkcheck: + @for lang in $(LANGUAGES);\ + do \ + mkdir -p $(BUILDDIR)/linkcheck/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/linkcheck/$$lang;\ + done + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck//output.rst." + +labels: + @for lang in $(LANGUAGES);\ + do \ + mkdir -p $(BUILDDIR)/labels/$$lang $(BUILDDIR)/doctrees/$$lang; \ + $(SPHINXBUILD) -b labels $(ALLSPHINXOPTS) $$lang $(BUILDDIR)/labels/$$lang;\ + cp $(BUILDDIR)/labels/$$lang/labels.rst $$lang/include/labels.inc;\ + done + @echo + @echo "Label generation complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/labels//labels.rst." + + +all: html all-pdf epub all-ps diff --git a/en/index.rst b/en/index.rst new file mode 100644 index 000000000..754b19572 --- /dev/null +++ b/en/index.rst @@ -0,0 +1,29 @@ +This is the QField documentation +=============================== + +QField is an alternative and simplified user interface for QGIS. It is built +with focus on mobile, touch driven devices. + +.. This document can also be downloaded as a single PDF document: `QGEP.pdf <./QGEP.pdf>`__ |image|. + .. |image| image:: ../_static/pdf.png + :height: 15 + :width: 15 + :alt: PDF icon + :target: QGEP.pdf + +Contents +======== + +.. toctree:: + :maxdepth: 2 + + installation-guide/index + project-management/index + user-guide/index + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + diff --git a/en/installation-guide/index.rst b/en/installation-guide/index.rst new file mode 100644 index 000000000..23f94ca11 --- /dev/null +++ b/en/installation-guide/index.rst @@ -0,0 +1,4 @@ +QField Installation Guide +========================= + +Get the app from PlayStore. diff --git a/en/project-management/index.rst b/en/project-management/index.rst new file mode 100644 index 000000000..fcc79a7b6 --- /dev/null +++ b/en/project-management/index.rst @@ -0,0 +1,12 @@ +QField Project Management +========================= + +You will need a portable version of your QGIS project file (.qgs). Portable +means that all paths are relative and datasets are reachable from the device. + +Data sources +............ + +While many data providers are supported, there are still some stability issues +with the OGR provider (E.g. Shapefile). For best stability you should use +spatialite files or a postgis database. diff --git a/en/user-guide/index.rst b/en/user-guide/index.rst new file mode 100644 index 000000000..339b41fa6 --- /dev/null +++ b/en/user-guide/index.rst @@ -0,0 +1,7 @@ +QField User Guide +================= + +Identifying features +.................... + +A long press on a feature will identify it. diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000..7bd6e6efe --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +sphinx==1.3.1 +Pygments>=2.0.1 diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh new file mode 100755 index 000000000..8291f8d12 --- /dev/null +++ b/scripts/build-docs.sh @@ -0,0 +1,11 @@ +#!/bin/bash + +# Exit on error +set -e + +DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )/.. +pushd ${DIR} +make clean +make html +make all-pdf +popd diff --git a/scripts/ci/deploy-docs.sh b/scripts/ci/deploy-docs.sh new file mode 100755 index 000000000..914bbd13a --- /dev/null +++ b/scripts/ci/deploy-docs.sh @@ -0,0 +1,26 @@ +#!/bin/bash + +# Exit on error +set -e + +DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )/../.. + +if test "$TRAVIS_SECURE_ENV_VARS" = "true" -a "$TRAVIS_BRANCH" = "master"; +then + echo "Publish docs to https://qfield.github.io/docs"; + + pushd ${DIR} + mkdir publish + cd publish + git clone git@github.com:opengisch/QField-docs.git --branch gh-pages + cd docs + git rm . -r + cp ../../build/html/* . -r + touch .nojekyll + git add -A + git commit -m "Automatic update from https://github.com/opengisch/QField-docs/commit/${TRAVIS_COMMIT}" + git push + popd +else + echo "Not publishing: Not the latest master version." +fi diff --git a/scripts/ci/setup_git.sh b/scripts/ci/setup_git.sh new file mode 100755 index 000000000..0b3ef93fc --- /dev/null +++ b/scripts/ci/setup_git.sh @@ -0,0 +1,10 @@ +#!/bin/bash + +if test "$TRAVIS_SECURE_ENV_VARS" = "true" -a "$TRAVIS_BRANCH" = "master"; +then + openssl aes-256-cbc -K $encrypted_cd22de430b6c_key -iv $encrypted_cd22de430b6c_iv -in opengisch_rsa.enc -out ~/.ssh/id_rsa -d; + chmod 600 ~/.ssh/id_rsa; + git config --global user.email "info@opengis.ch"; + git config --global user.name "opengisch"; + git config --global push.default simple; +fi diff --git a/scripts/create_transifex_resources.sh b/scripts/create_transifex_resources.sh new file mode 100755 index 000000000..a5b417531 --- /dev/null +++ b/scripts/create_transifex_resources.sh @@ -0,0 +1,70 @@ +#!/bin/bash + +# This script is used to register InaSAFE translatable resources with Transifex +# http://transifex.com +# +# Note that this script updates or creates entries in .tx/config file +# +# Tim Sutton, March 2013 + +# +# Sphinx documentation first +# + +#LOCALES=`ls i18n` +LOCALES='de fr it ro' + +# Exit on error +set -e + +DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )/.. + +# to be sure there are no pot files left +make clean +make gettext + +pushd ${DIR} +for POFILE in `find i18n/pot/${ITEM}/ -type f -name '*.pot'` +do + # get the po file, replacing 'en' with '' and removing double '//'s in path + GENERICFILE=`echo $POFILE | sed 's|//|/|g'` + # Get the filename-only part of the po file so we can use that + # name when registering the resource + BASE=`dirname $GENERICFILE`/`basename $GENERICFILE .pot` + # replace _ in - in filenames + # replace empty spaces to - + # replace / in _ + # replace . to _ (eg for release2.0 names) + # so we have for a file like + # site/about/my_screenshots/index.po + # we will get + # site_about_my-screenshots_index + RESOURCE=qfield-documentation.`echo $BASE | sed 's|i18n/pot/||g' | sed 's|[_ /\.]|-|g'` + echo "*** RESOURCE: $RESOURCE" + # Register each pot file as a transifex resource (an individual translatable file) + set -x + tx set -t PO -r $RESOURCE --source -l en "$GENERICFILE" + #set +x + # Now register the language translations for the localised po file against + # this resource. + for LOCALE in $LOCALES + do + echo $POFILE + LOCALEFILE=`echo $BASE | sed "s|/pot/|/$LOCALE/|g"`.po + #echo "$LOCALEFILE" + tx set -r $RESOURCE -l $LOCALE "$LOCALEFILE" + done + # When we are done in this block we should have created a section in the + # .tx/config file that looks like this: + # + # [qgis-website.site_forusers_alldownloads] + # file_filter = i18n//LC_MESSAGES/site/forusers/alldownloads.po + # source_file = i18n/en/LC_MESSAGES/site/forusers/alldownloads.po + # source_lang = en + # trans.nl = i18n/nl/LC_MESSAGES/site/forusers/alldownloads.po + # type = PO +done +popd + +#Print out a listing of all registered resources +#tx status