Page MenuHomePhabricator

Documentation System
Updated 192 Days AgoPublic

General idea

With nearly all APIs being written within Eo files, it also makes sense to have documentation in the same place. This page describes how to write documentation well integrated with our Eo files.

Current infrastructure

Our "new" docs are stored in a Dokuwiki, currently https://www.enlightenment.org/docs (https://www.enlightenment.org/docs/efl/auto/reference for a direct generated doc link).

  1. Eo files are parsed by a documentation generator (we have our own, gendoc.lua, written using Elua and Eolian bindings).
  2. Namespaced Dokuwiki file structure is generated, into its own "auto" namespace.
  3. These are directly used by Dokuwiki, the generated content depends on a few Dokuwiki plugins that have to be installed. A few are optional and can be turned off during generation time, by default everything is enabled.
  4. User-written docs are allowed directly on the wiki. This is handled by separating the Dokuwiki namespaces for autogeneated and user docs; generated docs are in "auto" but user docs are in "user". The generated docs contain special sections into which the user docs are included, so regenerating auto docs preserves user docs correctly.

Setting up a local Dokuwiki

From scratch

One way to get a local instance up and running is setting up a clean Dokuwiki installation from scratch. This section describes exactly that. Please refer to the below section to see how to set up an instance from an existing Enlightenment dokuwiki tree. That way is easier but doesn't give you the latest version of Dokuwiki and plugins.

  1. Download Dokuwiki from https://download.dokuwiki.org/.
  2. Unpack it, so that /path/to/dokuwiki contains index.php and install.php.
  3. Make sure PHP is correctly set up on your system. You don't need any database or any web server.
  4. Go to the Dokuwiki directory in your terminal and run something like php -S localhost:9001, replace 9001 with a port number you want it accessible with.
  5. Open your web browser and go to http://localhost:9001/install.php or the port number you selected.

At this point, installation dialog should show up. It might warn you about missing PHP modules or something else. Follow the instructions and fix those warnings first by installing the appropriate packages, instructions will differ depending on your OS and current setup.

Refresh the page to check if the issues are fixed. Keep doing that until there are no more warnings. Then proceed with the installation and create a superuser account and everything else as it asks you. After that, your new wiki installation is accessible on http://localhost:9001 (or your desired port number).

Necessary dokuwiki plugins

There are some Dokuwiki plugins the generated docs expect to be present (some are optional and can be turned off during documentation generation time, see --help on gendoc.lua). You can install those directly through Dokuwiki admin GUI. Namely, they're these:

Keep in mind that the plugins marked optional are still highly recommended and default settings for gendoc.lua keep all functionality enabled.

Using the existing tree

This is a bit easier to set up because you don't have to install all the plugins, it contains many extra plugins as well, a custom theme and all, but it may be out of date and requires some extra precautions when generating new docs.

Clone the following repository:

git clone https://git.enlightenment.org/website/www.git dokuwiki

This is the actual Dokuwiki tree itself. It doesn't work alone as it doesn't have the media and pages directories. Proceed into the public_html directory:

cd dokuwiki/public_html

This is where you will need to run PHP from. But first, clone the repository containing the additional directories.

cd data
git clone https://git.enlightenment.org/website/www-content.git

The tree is set up so that the directories need to be in data/www-content (unlike ordinary Dokuwiki setup where it's just data).

Now set up your account information:

cd .. # back into public_html
cp ../local.php.sample conf/local.php
echo "admin:\$1\$klvIJCLT\$JubROWbM1IEZyoto/LSRD.:Admin:root@localhost:admin,user" >> conf/users.auth.php

By default, a config option to rewrite links/URLs to make them prettier is specified. This will not work unless you're testing in Apache (as .htaccess files are shipped) or you're using some other web server where you can configure rewrite rules (such as nginx). That's why you need to disable this option by modifying public_html/conf/local.php and changing

$conf['userewrite'] = '1';

to

$conf['userewrite'] = '0';

Now the setup is complete, with admin as admin user name and password also admin. You may proceed to run it, from public_html:

php -S localhost:9001

And access the wiki in your web browser as usual.

Generating docs

First make sure you have current EFL set up and installed. Then checkout the gendoc repository (https://git.enlightenment.org/devs/q66/docgen.git) and run elua gendoc.lua ARGUMENTS .

By default gendoc will scan the installed Eo files to create the documentation. To change this and use a local directory simply add a directory parameter to specify the location (i.e. /path/to/efl/src/lib).

You don't actually have to provide any arguments to generate docs with the default settings. It does however expect a Dokuwiki installation to be in ./dokuwiki. A good way to do it is to symlink your Dokuwiki directory to here. Alternatively, you can also pass the path as in elua gendoc.lua --root=/path/to/dokuwiki/data/pages, see --help for available options.

Differences for Enlightenment dokuwiki tree

Keep in mind that when using a Dokuwiki setup made from the existing Enlightenment installation, its pages directory is not in data/pages, it's in data/www-content/pages. Therefore, you need to provide the --root option as following:

elua gendoc.lua --root=/path/to/dokuwiki/data/www-content/pages

If you have a symlink from public_html to dokuwiki in the directory you're running elua from, you could do something like

elua gendoc.lua --root=./dokuwiki/data/www-content/pages

When generating new docs, old docs present in the dokuwiki installation are automatically removed first. Only auto docs are removed, user docs are not affected.

TODO

  • Add more content here
  • Add updated version of content from previous version of this page here

FAQ

Last Author
stefan_schmidt
Last Edited
Nov 8 2018, 2:47 AM
Projects
None
Subscribers
ajwillia.ms, stefan_schmidt, q66 and 2 others