This part provides a detailed description on the usage of PID methodology’s core concepts and tools to deal with
When developing a PID framework one need to handle information such as:
- meta-information : who is involved in its development ? what is its general purpose ? where to find this framework on the network ? what is the license applying to its source files ? etc.
- functional information : this is the source code of the web pages and other associated files like configuration files if any required.
The whole package development is organized and described with CMake, and the
CMakeLists.txt files used contain the whole meta-information used by the framework. Each framework contains a unique
CMakeLists.txt file that is used to define meta-information.
Here is the root
CMakeLists.txt file of the framework used to generate the website you are currently reading:
Exactly as in any CMake project, the CMake package is defined with the
PROJECTkeyword. The CMake project’s name must be the same as the name of the git repository and must be the same as the project root folder name. The remaining lines until the
declare_PID_Frameworkmacro call must be let unchanged (initialization of the PID specific cmake API).
Then comes the
declare_PID_Framework) macro, which is mandatory. This macro defines general meta-information on the package, and should not change a lot during package life cycle:
- the main author (
AUTHORkeyword) and its institution (
INSTITUTIONoptional keyword), considered as the maintainer of the framework.
- the main author mail should be added (using
YEARargument helps defining the framework’s life cycle range. For instance one can input a field such as “2009-2013”.
LICENSEargument is used to specify the license that applies to the source code of web pages. This license must be defined in the workspace in the form of a license file.
ADDRESSargument is used to specify the address of the GIT repository of the framework.
DESCRIPTIONargument must be filled with a short description of the framework purpose.
SITEargument must be filled with the URL of the online site resulting from this framework.
PROJECToptional argument may be used to specify the URL of the online project page of the framework’s git repository.
LOGOimage can be defined. It specifies a path to a little image used in every page of the framework. This path is relative to the
assetsfolder of the framework.
BANNERimage can also be defined. It specifies a path to a big banner image used in the introduction page of the framework. This path is relative to the
assetsfolder of the framework.
- the main author (
PID_Framework_Categoryfunction is used to specify to which categories the framework contributes. A Category is nothing more than a text identifier that tells what concerns are used to arrange packages belonging to that framework. Many categories can be defined by the same framework. This information is used to classify packages and finally impacts the static web site resulting from the framework.
The last command called by the
build_PID_Frameworkmacro. This line is mandatory in order to allow the build of the framework. Without this call, the CMake process would simply do nothing.
To write the documentation, users need only to edit one of the follwoing markdown files, located in the
more.md. Each of these files will have a dedicated submenu in the
Documentation tab of the resulting static site and will so act as entry points for your documentation. Users can directly write all their documentation inside these predefined files, but most of time (and notably for the
more.md page) they will also be used to give pointer to other user defined pages. These pages simply have to be added to the
pages folder of the framework.
These files may contain mixed markdown/html syntax. For thoses unfamiliar to markdown you can have a look at this wikipedia page for starting.
To be short, here is the way to create a simple structured text in markdown:
And of course you can put some html inside, for instance:
These markdown pages are a bit specific as they will be interpreted by the jekyll tool. They all have a specific header that look like this:
To modify the title of the page simply change the value of the
title field, but it is not recommanded for predefined files.
As these files are interpreted by jekyll you can also use a bit more complex structures known as liquid tags and objects. Liquid is a template langage that helps generating text in a very flexible manner. It is widely used to generate the general look and feel of the framework resulting static site and adapt it regarding framework content (i.e. packages).
To keep it simple the most widely used liquid tags for end users should be those used to beautify the code, like:
Generating the static site
Finally, when documentation has been written the user has to first configure the framework:
Then simply launch the build process:
And if you want to test the resulting static site:
Look at the address provided by the output of the serve command. Use a web browser to see the result by typing this address.