Skip to content
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Bountysource Build Status

Stays crunchy, even in milk.

This package contains build-tools used to generate and ideally shouldn't be used to generate other pages.


In order to build the docs you will need the following:

  • valadoc past this commit
  • php
  • 4 GB of free space

On elementary OS or Ubuntu run:

sudo add-apt-repository ppa:vala-team
sudo apt update
sudo apt install valac valadoc libvaladoc-dev unzip php php-curl

Arch or derivatives run:

pacman -S vala php

Next, install JS dependencies:

npm install

After you have valadoc installed, you can move to building the documentation. Simply run:

make serve

and grab yourself a cup of coffee, or:

make serve-mini

for a minimal test version. This will take a bit of time. If you encounter an error at this step, please see the common pitfalls section. After you completed building, you should see a folder.

To access the documentation navigate your browser to http://localhost:7777.


For a more complete experience, you will need to install sphinxsearch and xsltproc.

On elementary OS or Ubuntu run:

sudo apt install sphinxsearch xsltproc

The run the following commands to generate search indexes:

make configgen
./configgen ./
mkdir ./sphinx/storage
indexer --config ./sphinx.conf --all
searchd --config sphinx.conf

This will start a sphinx daemon on port 51413.

Add New Packages

Open documentation/packages.xml and add a new package-entry.

Use <external-package> to create external links:

<external-package name="package-name" link="http://path/to/docs">
  short description

Use <package> to build and include documentation for vapi files:

<package name="gdl-1.0">
  short description

The following attributes are supported:

Name Description
name The vapi name
deprecated Set it to '"true"' to mark a package as deprecated
maintainers List of binding maintainers
gir The GIR file used to extract documentation from
c-docs Link to C documentation
ignore Do not build documentation for this entry
home Homepage link
flags Additional vala flags (Missing dependencies, ...)
gallery Link to a GTK-Doc widget gallery
vapi-image-source Source to download images from

Referenced GIR and vapi-files have to be part of one of the following repositories:

Add New Source Code Examples

Copy your examples to examples/<vapi-name>/ and add a new entry to examples/<vapi-name>/<vapi-name>.valadoc.examples:

  <title>Example Title</title>
  <compile>valac file-name1.vala file-name-2.vala ...</compile>

Add Handwritten Documentation

Create a new file called <vapi-name>.valadoc in documentation/<vapi-name>/:


 * My valadoc comment

 * My valadoc comment

Tool Overview

  • generator: Parses packages.xml files describing all packages. It is responsible for building up the page. It fetches resources such as images from specified sources, computes valadoc-calls, builds documentation for specified packages and puts-together the whole page. (make serve, make serve-mini)
  • configgen: Used to generate configuration files for our search index.
  • valadoc-example-gen: Internally used to generate example listings.
  • valadoc-example-tester: Compiles and checks all registered examples. (make test-examples)

Common Pitfalls

Uncaught Error: Class 'mysqli' not found

  • Uncomment in your OS's php.ini (find /etc -name php.ini)

error: failed to load driver

  • Your valadoc version does not support the requested vala version. Install a recent vala version and recompile valadoc.
  • Change VALAC_VERSION in Makefile.

Other errors:

  • Check LOG in the root of this repo for more information
  • Have you run out of disk space?

Contact And Help

You can’t perform that action at this time.