No description, website, or topics provided.
Clone or download
Pull request Compare This branch is 1 commit ahead, 1 commit behind flobrosch:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
data
documentation
examples
sphinx
src
.gitignore
Makefile
README.md

README.md

Valadoc-org

Stays crunchy, even in milk.

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

Building

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;

Arch or derivatives run:

yaourt -S valadoc-git php

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 valadoc.org folder.

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

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
</external-package>

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

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

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:

<example>
  <title>Example Title</title>
  <image>optional-screenshot.png</image>
  <file>file-name-1.vala</file>
  <file>file-name-2.vala</file>
  <compile>valac file-name1.vala file-name-2.vala ...</compile>
  <node>Associated.Symbol.name1</node>
  <node>Associated.Symbol.name2</node>
</example>

Add Handwritten Documentation

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

...

/**
 * My valadoc comment
 */
c::c_symbol_name
...

/**
 * My valadoc comment
 */
Vala.Symbol.Name

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 extension=mysqli.so 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