KiCad Documentation

This repository contains the official link:http://www.kicad-pcb.org/[KiCad] documentation.

image:http://ci.kicad-pcb.org/buildStatus/icon?job=any-kicad-doc-head["Build Status", link="http://ci.kicad-pcb.org/job/any-kicad-doc-head/"] image:https://img.shields.io/badge/docs-stable-brightgreen.svg["Stable version docs", link="http://docs.kicad-pcb.org/"] image:https://img.shields.io/badge/docs-nightly-lightgrey.svg["Nightly docs", link="http://ci.kicad-pcb.org/job/any-kicad-doc-head/lastSuccessfulBuild/artifact/src/"]

== Contributing

You can discuss the documentation and its translations in the link:https://github.com/KiCad/kicad-doc/issues[repository issues].

To participate to the translation effort read the link:translation_instructions.adoc[]. + Submit your translation pull requests to the master branch, please. + See link:docs-versioning.adoc[] for details about docs versioning.

The following instructions explain how to test changes before link:https://github.com/KiCad/kicad-doc/fork[submitting a pull-request].

== Dependencies

• http://asciidoc.org/[AsciiDoc] >= 8.6.9 is both the language of the documentation and the tool used to generate the PDF and HTML outputs.

We will probably switch to http://asciidoctor.org/[asciidoctor] in the future, when asciidoctor tools are stable enough, because of their ability to generate PDF and epub document formats directly without the intervention of any other external tool or intermediate format like dblatex or docbook. See the http://asciidoctor.org/docs/convert-asciidoc-to-pdf/[asciidoctor-pdf] project.

• https://po4a.alioth.debian.org/[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 LANGUAGES option to avoid build errors.
• For building PDF files with Cyrillic characters (like Russian) the fonts package freefont-ttf is required, so you will need to look for similar named package.

=== Debian / Ubuntu

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

sudo apt-get install asciidoc cmake dblatex fonts-freefont-ttf \
fonts-vlgothic gettext git make po4a source-highlight \
texlive-lang-cyrillic texlive-lang-english texlive-lang-european \
texlive-lang-french texlive-lang-german texlive-lang-italian \
texlive-lang-japanese texlive-lang-other texlive-lang-polish \
texlive-lang-spanish texlive-xetex texlive-lang-chinese \
libunicode-linebreak-perl

NOTE: Debian Jessie and Ubuntu 16.04 LTS has no package texlive-lang-european, install the package texlive-lang-dutch instead.

NOTE: in Ubuntu 14.04 LTS there is no texlive-lang-japanese. Install texlive-lang-cjk instead.

or, if you do not have space problems:

sudo apt-get install asciidoc cmake dblatex fonts-freefont-ttf \
fonts-vlgothic gettext git make po4a source-highlight \
texlive-lang-all texlive-xetex libunicode-linebreak-perl

=== Fedora

To install the dependencies on Fedora run the following:

sudo dnf install git make cmake asciidoc gettext po4a dblatex \
source-highlight texlive vlgothic-fonts perl-Unicode-LineBreak \
texlive-scheme-full texlive-collection-xetex gnu-free-serif-fonts \
gnu-free-mono-fonts gnu-free-sans-fonts

=== Manjaro Linux

To install the dependencies on Manjaro run the following:

sudo  pacman -S asciidoc cmake dblatex ttf-freefont gettext \
po4a source-highlight  texlive-langchinese texlive-langcyrillic \
texlive-langjapanese texlive-langextra texlive-langkorean \
texlive-langgreek perl-unicode-linebreak

NOTE: AUR package

yaourt -S ttf-vlgothic

== Building the docs

=== Windows

Start with link: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 link: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.

==== LANGUAGES

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

You can build just one or some of the languages by using the LANGUAGES option when configuring a build with CMake, e.g. -DLANGUAGES="it;en;de", etc.

Currently, the available languages are : ca, de, en, es, fr, id, it, ja, pl, ru and zh, 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.

==== SINGLE_LANGUAGE

This option is deprecated, use LANGUAGES instead

==== 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