# kicad-doc

**Repository Path**: KiCAD-CN/kicad-doc

## Basic Information

- **Project Name**: kicad-doc
- **Description**: KiCad new documentation repository
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 11
- **Forks**: 4
- **Created**: 2019-03-10
- **Last Updated**: 2025-07-08

## Categories & Tags

**Categories**: ebooks-manual

**Tags**: None

## README

KiCad Documentation
===================

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


== Contributing

To help the development of the documentation, add issues to the
link:https://gitlab.com/kicad/services/kicad-doc/issues[issues page].

To help in translating the documentation visit the link:translation_instructions.adoc[]. +

To contribute code to the repository,
link:https://gitlab.com/kicad/services/kicad-doc/-/forks/new[fork the project],
commit changes to a branch on your fork, and
link:https://gitlab.com/kicad/services/kicad-doc/-/merge_requests[submit a merge request]. +
Submit your merge requests to the nightly docs branch `master`. If applicable,
your changes will also be applied to the stable branch after merging.

== Dependencies

* https://asciidoctor.org/[Asciidoctor] >= 2.0 is both the language of the
documentation and the tool used to generate the HTML outputs.

* https://github.com/Mogztter/asciidoctor-web-pdf[asciidoctor-web-pdf] is used to generate the
  PDF outputs.

* https://www.po4a.org/[po4a] v0.44 < version < v0.55 is used to translate the English
AsciiDoc documentation to other languages before the last compilation steps.
* CMake >= 3.0
* gettext >= 0.18

=== Debian / Ubuntu

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

----

sudo apt-get install cmake ruby npm ninja-build fontconfig \
fonts-freefont-ttf fonts-wqy-microhei fonts-vlgothic gettext \
git make po4a source-highlight libunicode-linebreak-perl

sudo gem install asciidoctor

sudo npm i -g @asciidoctor/core asciidoctor-pdf --unsafe-perm

----

=== Fedora

To install the dependencies to build the documentation on Fedora, run the following:

   sudo dnf install -y cmake fontconfig po4a rubygem-asciidoctor npm git wqy-microhei-fonts
   sudo npm install -g puppeteer --unsafe-perm=true
   sudo npm install -g @asciidoctor/core asciidoctor-web-pdf --unsafe-perm=true

=== Arch/Manjaro Linux

To install the dependencies on Arch/Manjaro run the following:

    sudo pacman -S asciidoctor fontconfig po4a cmake gettext \
        perl-unicode-linebreak source-highlight ttf-freefont wqy-microhei

    yay -S asciidoctor-web-pdf ttf-vlgothic

== Building the docs

=== MacOS / Linux

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

or: Use ninja for accelerated compilation (Note: ninja needs to be installed)

    cd kicad-doc
    mkdir build
    cd build
    cmake -G Ninja ..
    ninja

=== Docker
https://gitlab.com/kicad/kicad-ci/doc_containers contains the base docker image with the tools preinstalled
to build the docs, if there is a need to update the base image, it must be done in that repo.

This repo contains its own Dockerfile intended to base on the build tools docker image and generate an empty
"archive" docker with just the generated files

=== CMake Build Options

==== BUILD_FORMATS

By default **BUILD_FORMATS** is set to `"html;pdf"` 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.

==== DOC_VERSION and DOC_COMMIT

These variables are used to set the version information printed in the
documentation. By default, these are set to reasonable values, so anyone
building the docs does not necessarily need to set these variables.

* `DOC_VERSION`: The current KiCad application version described by the docs
being built, in `major.minor.patch` format. If not specified, the value set in
this repository is used (see `CMakeModules/VersionInfo.cmake`).
* `DOC_COMMIT`: This is intended to be set to the current documentation commit
hash (i.e. the most recent commit hash in this repo). This value is printed
verbatim in the docs. If not specified, it is defaulted to the value of
`DOC_VERSION`, so the `major.minor.patch` version is printed instead of the
documentation commit hash.

Note that the defaults are fine for local development where you don't care
about the documentation containing accurate version numbers, commit hashes,
etc. The defaults are also probably fine for downstream packaging usecases.

==== PDF_GENERATOR

By default CMake will use `asciidoctor-web-pdf` for building PDFs. This is the
only supported PDF generator.

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

== Translating the docs

See the link:translating/translation_instructions.adoc[translation instructions].