KiCad Documentation

This repository contains the official KiCad documentation.

Contributing

You can discuss the documentation and its translations in the repository issues.

To participate to the translation effort read the translation_instructions.adoc.

The following instructions explain how to test changes before submitting a pull-request.

Dependencies

AsciiDoc >= 8.6.9 is both the language of the documentation and the tool used to generate the PDF and HTML outputs. We don’t use asciidoctor because PDF generation is currently missing support for inline images (see the asciidoctor-pdf project).
po4a >= 0.45 is used to translate the English AsciiDoc documentation to other languages before the last compilation steps.
CMake >= 2.8
dblatex >= 0.3.4
gettext >= 0.18
source-highlight
The VL Gothic font is required when you build the japanese PDFs. Look for a package named fonts-vlgothic. Otherwise use the SINGLE_LANGUAGE option to avoid build errors.

Debian / Ubuntu

To install the dependencies on Debian / Ubuntu run the following (requires about 1.5GiB of space):

sudo apt-get install git make cmake asciidoc pandoc gettext po4a dblatex
texlive-xetex fonts-vlgothic source-highlight texlive-lang-english
texlive-lang-french texlive-lang-italian texlive-lang-japanese
texlive-lang-dutch texlive-lang-polish texlive-lang-german

Note	in Ubuntu 14:04 there is no texlive-lang-japanese. Install texlive-lang-cjk instead.

Note	in Debian Jessie the package texlive-lang-dutch is a transitional package, Install texlive-lang-european instead.

or, if you do not have space problems:

sudo apt-get install git make cmake asciidoc pandoc gettext po4a dblatex
texlive-xetex fonts-vlgothic source-highlight texlive-lang-all

Fedora

To install the dependencies on Fedora run the following:

sudo dnf install git make cmake asciidoc pandoc gettext po4a dblatex
source-highlight texlive vlgothic-fonts perl-Unicode-LineBreak
texlive-scheme-full texlive-collection-xetex

Building the docs

Windows

Start with windows_dependencies.adoc then run:

cd kicad-doc
mkdir build
cd build
cmake -G "MinGW Makefiles" -DPDF_GENERATOR=FOP ../
make

MacOS / Linux

cd kicad-doc
mkdir build
cd build
cmake ../
make

Docker

Read utils/docker/README.adoc if you want to build the documentation in a container.

CMake Build Options

BUILD_FORMATS

By default BUILD_FORMATS is set to html;pdf;epub to enable building all supported document formats.

It’s possible to set BUILD_FORMATS in order to build only a subset of formats, e.g. -DBUILD_FORMATS=html

When only one build format is enabled the package name is transformed to include the format.

SINGLE_LANGUAGE

By default CMake will configure to build all languages available for each document.

You can build just a single language by using the SINGLE_LANGUAGE option when configuring a build with CMake, e.g. -DSINGLE_LANGUAGE=it, etc.

Currently, the available languages are : en, fr, it, ja, nl, and pl however, any language code can be selected. Only translated documents will be built, so for some languages there may only be a partial documentation output.

When the SINGLE_LANGUAGE option is set, the package name is transformed to include the language.

PDF_GENERATOR

By default CMake will use dblatex building PDFs.

You can build PDFs however using either DBLATEX or FOP by using the PDF_GENERATOR option whilst configuring a CMake build.

For example, use -DPDF_GENERATOR=FOP to use FOP to build the PDFs. If the BUILD_FORMATS option doesn’t include pdf, the PDF_GENERATOR option will have no effect on the build.

This option doesn’t transform the built package name.

Packaging the docs

The docs use CMake as mentioned earlier, so to install it as a packager use the normal CMake way, for example:

mkdir build; cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
make install

And if on OS X you might want something like:

mkdir build; cd build
cmake -DCMAKE_INSTALL_PREFIX="/Library/Application Support/kicad" ..
make install

caerbannog / kicad-doc Goto Github PK

kicad-doc's Introduction