README 3.58 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
==========================================
libgo -- script to build library.gnome.org
==========================================


Installation
============

libgo is made to run from its checkout directory, there is no need for
installation.

12
13
14
configure and make are used to build translations, running ./autogen.sh
&& make will build the necessary bits.  Dependencies are gettext,
xsltproc, gnome-doc-utils, and yelp-tools.
15
16
17
18
19
20
21
22
23
24
25


Usage
=====

usage: lgo.py [options]

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config=CONFIG
  -v, --verbose         verbosity level (more -v for more verbose)
26
  --rebuild=FILENAME    rebuild documentation from FILENAME
27
28
  --rebuild-all         rebuild all documents (even those that were already
                        built)
29
30
  --rebuild-language=LANGUAGE
                        rebuild all documents in LANGUAGE
31
32
  --skip-extra-tarballs
                        don't look for documentation extra tarballs
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

Example: python src/lgo.py -c sample.lgorc -v -v -v

Note about verbosity: xsltproc output is not redirected to /dev/null and will
amount for most of the output.


Configuration File
==================

lgo will look at ~/.lgorc, it can be overridden with -c.

sample.lgorc is a sample configuration file, src/defaults.lgorc lists all
variables and their default settings.

Notable configuration variables are:

 - ftp_gnome_org_local_copy: path to local copy of ftp.gnome.org, this is
   used not to download all the files that are already local.
52

53
54
55
56
57
58
59
 - download_cache_dir: path to download cache directory (default:
   ~/.lgo/cache/)

 - output_dir: path to web output (default: /var/www/library.gnome.org/)

 - version_min, version_max: minimum/maximum GNOME version to have
   documentation for (absolute minimum is 2.12.0).
60

61
62
63
64
65
66
67
68
   Note about versions:
    - libgo will only build the latest version of a serie,
    - libgo will only build the latest version of the latest development
      serie.

 - modules: list of modules to use (default: None, meaning all modules);
   this can be used to restrict modules to a specific subset, example:
   ['eog', 'gedit']
69

70
71
72
 - languages: list of languages to build (default: None, meaning all
   languages); this can be used to restrict languages to a specific subset,
   example: ['en', 'sv', 'ja', 'es']
73
74


75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
Apache Configuration
====================

libgo generates a static website, to be served by Apache using its MultiViews
mode for language negociation, a working virtualhost would be:

  <VirtualHost *:80>
    ServerName library.gnome.org
    DocumentRoot /var/www/library.gnome.org/

    <Directory /var/www/library.gnome.org/>
      Options All
      AllowOverride All
      Require all granted
      Options +MultiViews
    </Directory>

    # Make it possible to use a cookie to negociate language
    LanguagePriority en
    ForceLanguagePriority Prefer Fallback
    SetEnvIf Cookie "language=(.+)" prefer-language=$1 Header append
    Vary cookie
    Header append Vary Cookie
  </VirtualHost>


101
102
103
104
105
106
107
108
109
System Requirements
===================

To build everything from 2.12 to current 2.19 development version :

 - disk usage:
   - download cache (everything from ftp.gnome.org): 829M
   - extracted files: 679M
   - web site: 624M
110

111
112
 - time:
   - building and scanning all documentation: 2h40
113
   - scanning (already built) documentation: 0h20
114
115
116
117
118
119
120
121
122
123
124
125
126


Mode of operation
=================

- Using http://ftp.gnome.org/pub/GNOME/teams/releng/ to download GNOME jhbuild
  modulesets for requested versions
- Iterating on versions
  - Downloading tarballs
    - Looking for gtk-doc or gnome-doc-utils usage in tarball
      - Building them
- Creating indexes