[All bundles]

website

Version: 1.1
Run: website download_stats
Source: repository
Dependencies: lpdoc

The Ciao Website

This bundle contains the sources for the Ciao website. The file structure is as follows:

Manifest/           Manifest for this bundle
                    (includes some building code)
SITE.pl             Site definition (as an LPdoc doc)
src/                Website contents in LPdoc format.
tmpl/               Templates for special HTML contents
                    (instantiated from LPdoc commands).
skel/               Additional website files
                    (images, CSS files, etc.).
download_ui/        Download component (see below)

thumbnail_generation/ Directory for generation of thumbnails.

mailman/            Embedding of mailman in the website.
pbundle/            CLI command to fetch pbundles from CiaoBot
The original sources (including alternative versions) of the logos and images in this repository are stored separately in the ciao-artwork repository.

Using LPdoc to generate websites

This section describes some (experimental) features of LPdoc used to generate the website.

The structure and most of the contents of the website are generated with LPdoc, using the following declaration (at the SITE.pl file):

html_layout := website_layout(...).
Other LPdoc commands and markup:
  • section images:
:- doc(pragma, section_image(<File>)).
  • external HTML:
@html_template{<template>}
  • custom markup for downloading archives (enabled with load_doc_module := ciao_website(src/pbundle_download).):
@pbundle_uref{<text>}{<branch>}{<link>}{<file>}

@pbundle_download{<branch>}{<kind>}

Generation

Use the following steps to generate an up-to-date website:

  • Copy or update the release metadata under releases/
  • Fetch externals (fonts, etc.)
    ciao custom_run website fetch_externals
  • Update the website:
    ciao custom_run website dist
This will prepare the website files under CIAOROOT/build/site/ directory. Make sure that CIAOROOT/build/site/packages and CIAOROOT/build/site/docs are populated by the fetch command.

Serving the website

Use the ciao-serve command to start a simple HTTP server at http://localhost:8000 with support for dynamic content (like the download component). It can be customized to listen from another address and port or be combined with other HTTP servers a reverse proxy (see Deployment instructions later).

Data from the dynamic components of the website will be locally stored at the CIAOROOT/build/data/ directory.

Deployment at ciao-lang.org

The recommended way of setting up the website consists on starting the ciao-serve command on a dedicated host and port and configuring an HTTP reverse proxy.

To configure a reverse proxy in Apache use the commands:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_balancer
sudo a2enmod lbmethod_byrequest
sudo a2enmod lbmethod_byrequests
sudo systemctl restart apache2
and include a VirtualHost entry in /etc/apache2/sites-enabled/<yoursite>.conf:
<VirtualHost *:80>
    ServerName PUBLICHOST

    # OPTIONAL - Use a proxy block to redirect some addresses
    <Proxy *>
        RedirectMatch ^/$ "/path-to-first-entry"
    </Proxy>

    ProxyPass "/"  "http://PRIVHOST:PRIVPORT/"
    ProxyPassReverse "/"  "http://PRIVHOST:PRIVPORT/"

    <Location />
        Require all granted
    </Location>
</VirtualHost>

Additional notes

It is based on (yet undocumented) features of LPdoc to generate custom websites, by combining the HTML backend, new docstring markup commands, and CSS files provided by the user.

Note that, except for a few hard-wired texts and links, the code is really generic and it could be used in the generation of custom websites (for personal pages, other software, etc.).

Download component

In order to keep statistics and encourage users to subscribe to our mailing-lists, some file downloads are tunneled through download_ui.pl. See its documentation for more details.