This part provides a detailed description on the usage of PID methodology’s core concepts and tools to deal with frameworks.

Framework definition

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:

cmake_minimum_required(VERSION 3.15.7)
set(WORKSPACE_DIR ${CMAKE_SOURCE_DIR}/../../.. CACHE PATH "root of the frameworks workspace directory")
list(APPEND CMAKE_MODULE_PATH ${WORKSPACE_DIR}/cmake) # using generic scripts/modules of the workspace
include(Framework_Definition NO_POLICY_SCOPE)

project(pid)

PID_Framework(	AUTHOR 		Robin Passama
			MAIL		passama@lirmm.fr
			INSTITUTION	LIRMM
			ADDRESS 	git@gite.lirmm.fr:pid/pid-framework.git
	 		YEAR 		2016
			LICENSE 	CeCILL-C
			DESCRIPTION 	"PID is a global development methodology supported by many tools inclusing a CMake API and dedicated C++ projects."
			SITE		http://pid.lirmm.net/pid-framework
			PROJECT	https://gite.lirmm.fr/pid/pid-framework
			LOGO		img/pid_logo.jpg
			BANNER		img/cooperationmechanisms.jpg
		)

PID_Framework_Category(programming)
PID_Framework_Category(programming/filesystem)
PID_Framework_Category(programming/meta)
PID_Framework_Category(programming/resources_management)
PID_Framework_Category(programming/logging)
PID_Framework_Category(programming/configuration)

build_PID_Framework()

Explanations:

  • Exactly as in any CMake project, the CMake package is defined with the PROJECT keyword. 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 PID_Framework macro call must be let unchanged (initialization of the PID specific cmake API).

  • Then comes the PID_Framework (equivalent to 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 (AUTHOR keyword) and its institution (INSTITUTION optional keyword), considered as the maintainer of the framework.
    • the main author mail should be added (using MAIL optional keyword) to better document to resulting static site.
    • the YEAR argument helps defining the framework’s life cycle range. For instance one can input a field such as “2009-2013”.
    • the LICENSE argument 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.
    • the ADDRESS argument is used to specify the address of the GIT repository of the framework.
    • the DESCRIPTION argument must be filled with a short description of the framework purpose.
    • the SITE argument must be filled with the URL of the online site resulting from this framework.
    • the PROJECT optional argument may be used to specify the URL of the online project page of the framework’s git repository.
    • a LOGO image can be defined. It specifies a path to a little image used in every page of the framework. This path is relative to the assets folder of the framework.
    • a BANNER image 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 assets folder of the framework.

  • the PID_Framework_Category function 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 CMakeLists.txt must the build_PID_Framework macro. This line is mandatory in order to allow the build of the framework. Without this call, the CMake process would simply do nothing.

Writing documentation

To write the documentation, users need only to edit one of the follwoing markdown files, located in the src/pages folder: introduction.md, install.md, tutorial.md and 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:

# First level title

some introduction

## Second level title

more explanation

...

And of course you can put some html inside, for instance:

# First level title

some introduction

<image=img/my_image.png>

...

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:

---
layout: page
title: Using frameworks
---

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:

{% highlight cplusplus %}

#include <iostream>
void my_Function(){
  std::cout<<"Hello World"<<std::endl;
}

{% endhighlight %}

Generating the static site

Finally, when documentation has been written the user has to first configure the framework:

cd <framework folder>
pid configure

Then simply launch the build process:

cd <framework folder>
pid build

And if you want to test the resulting static site:

cd <framework folder>
pid serve

Look at the address provided by the output of the serve command. Use a web browser to see the result by typing this address.