Deployment units should be documented as precisely as possible. Indeed as anyone know this is a big concern regarding usage of code that have been developped.

In PID, documentation of deployment units (either packages or frameworks) is made with static sites. A static site is a bunch of static web pages. A static site is also the place where binary versions of packages can be put in order to make them accessible to everybody. Your are currently reading one of these static sites, the one of the PID framework.

To sum up, there are basically two ways of documenting packages:

  • with lone static site. Package documentation is put into a dedicated static site that is independent from any other site. This option should be avoided as soon as the package belong to a more coherent space.
  • with frameworks. Package documentation is put into a static site that groups many related packages. This is the preferred option as it provides a better navigation scheme for the user. Indeed in PID frameworks have be designed to do that: providing a global coherent space where related packages can be well registered, documented, and their binary versions deployed.

Now why using PID system to generate documentation for packages ? Well there are few reasons:

  • The documentation is standardized, once you know how to use one, you know how to use all documentation sites.
  • Everything is generated automatically, except for user defined content that helps customizing the site in a limited way.
  • You do not have to care about how to publish sites, notably how to manage continuous integration to do so.
  • It also lets you the possibility to create kind of repositories for you binaries, this way you even have no more to bother about the referencing and publishing of packages binaries, it will be done automatically.

Package

Documenting package with a lone static site is achieved with calling the PID CMake API directly in their root CMakeLists.txt file. For instance if the pid-rpath were documented using a lone static site it would look like:

declare_PID_Deployment(PROJECT https://gite.lirmm.fr/pid/pid-rpath
			GIT git@gite.lirmm.fr:pid/pid-rpath-pages.git
			PAGE http://pid.gite.lirmm.io/pid-rpath-pages
			DESCRIPTION pid-rpath is a package providing a little API to ease the management of runtime resources within a PID workspace. Runtime resources may be either configuration files, executables or module libraries. Its usage is completely bound to the use of PID system.
			ADVANCED specific_usage.md
			LOGO	img/rouage_PID.jpg
			PUBLISH_BINARIES)

This last command specifies that address of the site with PAGE keyword and address of the corresponding git repository with GIT keyword. The only thing you have to do by hand is to create and empty project on your gitlab server called pid-rpath-pages (or pid-rpath-site) and then let PID do the job. The PROJECT keyword is used to simply document the URL where to find the project page of the current package and will be used to generate hypertext links.

The LOGO keyword references a path to image that is located in the share/site folder of your package. This image will be used as a logo for the static site.

The ADVANCED keyword references a path to a file that provides specific content and that is located in the share/site folder of your package. It will be used to create a specific submenu in the package documentation that give access to a web page providing user defined documentation.

Finally the PUBLISH_BINARIES may be used to configure the lone static site in order to automatically publish binaries of the package.

The user can also add more documentation to components defined in the package. This way a complete an modular documentation can be performed.

Resulting static site

The result of the documentation generation is a static site that is:

  • a web site that looks like a kind of blog.
  • a repository for package binaries if PUBLISH_BINARIES has been used.

The web site structure (its menus, root pages, etc.) is standardized, as well as the content of pages describing the content of the package (how to use the package, its dependencies, its components and their dependencies, etc.).

To get an idea of the result simply look at any package provided by the PID framework. Indeed, even if these packages static sites are provided into a framework their look and feel is really close to the one of lone static site (as they are generated from exactly same content coming from package).

Publishing the static site by hand

Once done, the package site repository can be created/updated. This is automatically achived by calling the specific site target of the package:

cd <package path>/build
make site

This later command will:

  • update the package site repository by generating its content (markdown pages, configuration files, doxygen documentation, static check reports, new binary version archives, etc.) from the meta-information of the package and from user defined content.
  • build the package site to ensure that there is no problem.
  • commit and push the updated content to the static site repository master branch.

One important thing to understand is that this last action will lead to the launch of continuous integration process on the static site repositoy that will, in the end, generate and publish the static site using the gitlag pages mechanism. And so, the real publication of the website can be performed only with the continuous integration process. The mandatory steps to do that are:

  • to enable continuous integration for the static site repository if it is not already active. You can refer to this help page.
  • to configure a runner for the static site repository. Please ask the PID administrator to know which runner can be used. There is a specific runner used to build PID static sites. To configure the static site repository gitlab project you can refer to this help page

Looking at the web site on your local workstation

If you want to see the resulting web site on your workstation you can do the following commands:

cd <package path>/build
make site synchro=false

This command will do the same as previously except that it will not push to the server repository and so it will not launch the continuous integration process and, in the end, the publication of an updated web site. Then to see the result in you web browser:

cd <workspace>/sites/packages/<package name>/build
make serve

The output of the serve target will print the address where you can find the web site.

This approach is particularly useful if you want to see the resulting static when you edit userdefined pages.

Automatic publishing of the static site

The last option is in fact the default one and is complemetely transparent for the user. It is achieved each time the package is released:

  • the continuous integration (ci) process takes place and builds the package that has just been released. This will generate all the required information (doxygen documentation, coverage report if there are checks, static checks, markdown pages, etc.) depending on package meta-information and content.
  • the ci process then create/update the static site by doing:
cd <package path>/build
make site

This last step in turn launches the continuous integration process on the package site repository than will finally lead to the publication of the static site as explained before.

Framework

Frameworks are deployment units that have been designed specifically to manage the documentation and the deployment of groups of packages. Their main purpose is to generate static sites.

So when one wants to document a package belonging to a framework, the first step consist in creating a framework. To do so, user simply have to consult this help page. Once a framework has been created you then have to declare your package as a member of this framework.

Resulting static site

The result of the documentation generation is a static site that is a web site that looks like a kind of blog and a repository folder for packages version binaries.

The web site structure is standardized: its menus, its index page, its sidebar, as well as some of the pages any user intend to find (tutorial, install guide and introduction). User defined content is most of time necessary and it is implemented as more or less mixed markdown / html pages that can be accessed from standard pages.

To get an idea of the result simply look at the site your are currently reading. Indeed, PID is a development methodology but it is also a PID framework !

Difference between lone and framework static sites

There are a few differences between static site generated by a framework and those generated as lone static sites:

  • a framework site has a global menu bar that provides general information about the framework. This menu bar directly or undirectly gives access to different pages, like the one your are currently reading.
  • a framework site has a sidebar on left side, that gives access to package specific documentation. This sidebar arrange packages according to categories defined by the framework and categories packages contribute to.
  • a package specific documentation is always presented as an internal panel of the framework site, which always let the user the possibility to access the sidebar and the menubar, facilitating navigation between packages and easy access to general documentation.

Publishing the framework site

Any time a user modify the content of the framework, commit these modifications and then push these commits, the framework static site is generated via a continuous integration (ci) process.

The mandatory steps to do that are:

  • to enable continuous integration for framework repository if it is not already active. You can refer to this help page.
  • to configure a runner for the framework repository. Please ask the PID administrator to know which runner can be used. There is a specific runner used to build PID static sites. To configure the static site repository gitlab project you can refer to this help page

Then once a push or merge request has been performed on the framework repository, the ci process does something like:

cd <workspace>/sites/frameworks/<framework name>/build
make build

The result of the build command is the static site itself and is automatically uploaded to a dedicated web server in order to be published. This is achived by the gitlag pages mechanism.

Looking at the framework site locally

To look at the result on your local workstation, no need to push, there is a dedicated local command.

cd <workspace>/sites/frameworks/<framework name>/build
make serve

The output of the serve target will print the address where you can find the web site. Keep the serve command running in its own terminal, this way it will reload the static site any time it is generated. If the serve command runs in parallel, you then simply have to reload the framework site in your browser after any update of its content.

This approach is really useful if you want to debug user defined pages. So any time you update framework user defined pages just do:

cd <workspace>/sites/frameworks/<framework name>/build
make build

And then reload the framework site in you web browser and you will see the result.

Documenting packages into frameworks

Documenting packages within a framework static site is achieved by calling the PID CMake API directly in their root CMakeLists.txt file. For instance here is the code used in the root CMakeLists.txtof the pid-rpath package to specify that it is documented in the pid framework:

declare_PID_Publishing(	PROJECT https://gite.lirmm.fr/pid/pid-rpath
			FRAMEWORK pid
			DESCRIPTION pid-rpath is a package providing a little API to ease the management of runtime resources within a PID workspace. Runtime resources may be either configuration files, executables or module libraries. Its usage is completely bound to the use of PID system.
			ADVANCED specific_usage.md
			PUBLISH_BINARIES ALLOWED_PLATFORMS x86_64_linux-abi11)

It specifies that the package belongs to the pid framework using the FRAMEWORK keyword. The PROJECT keyword is used to simply document the URL where to find the project page of the current package and will be used to generate hypertext links.

The ADVANCED keyword references a path to a file that provides specific content and that is located in the share/site folder of your package. It will be used to create a specific submenu in the package documentation page that gives access to a web page providing user defined documentation.

Finally the PUBLISH_BINARIES may be used to configure the framework site in order to automatically publish binaries for the package.

There are more option to better document packages, you can first have a look at the macro documentation to get a more detailed description.

As with lone static sites, the user can also add more documentation to components defined in the package. This way a complete an modular documentation can be performed.

Publishing the framework site by hand

Once a package has been added to a framework or anytime its content has been singificantly updated, the framework repository should be updated as well. This is automatically achived by calling the specific site target of the package:

cd <package path>/build
make site

This later command will:

  • update the framework repository by generating the part of its content related to the package (markdown pages, configuration files, doxygen documentation, static check reports, new binary version archives, etc.) from the meta-information of the package and from user defined content at package level.
  • build the framework with jekyll to ensure that there is no problem.
  • commit and push the updated content to the framework repository master branch.

One important thing to understand is that this last action will lead to the launch of continuous integration process on the framework repositoy that will, in the end, generate and publish the static site using the gitlag pages mechanism exactly as explained before.

Looking at the web site on your local workstation

First you have to update the framework with the content generated by your package:

cd <package path>/build
make site synchro=false

This is the same process as previously except that there is no push to the framework online official repository. This action regenerates the framework static site by calling jekyll tool. You can see the result locally as explained here.

Automatic publishing of the static site

The last option is in fact the default one and is completely transparent for the user. It is achieved each time a package of the framework is released:

  • the continuous integration (ci) process takes place and builds the package that has just been released. This will generate all the required information (doxygen documentation, coverage report if there are checks, static checks, markdown pages, etc.) depending on package meta-information and content.
  • the ci process then update the framework content by doing:
cd <package path>/build
make site

This last step in turn launches the continuous integration process on the framework repository than will finally lead to the publication of the framework static site as explained before.

Documenting components

Documenting components of a package consits in adding a bit more user defined information to make the understanding of components usage easier.

A very lightweight way consists in simply adding very usefull information using specific keywords of the declare_PID_Component macro:

  • DESCRIPTION provides a short description of the utility of the component, and is used in many places like mardown pages of the static site and doxygen documentation.
  • USAGE provides the list of header files to include in order to use the component, if the component has a compile time interface (i.e. this is not useful for executables or module libraries). This information is also used in different places to produce more precise information.

Another way is to provide specific pages for component documentation. These pages will be used only in the static site of the component (either a framework or a lone static site). From CMake point of view it consists in using the declare_PID_Component_Documentation macro. The principle consists in binding the component to a specific marksdown file that contains a detailed description of the component and its usage. The markdown file must lie in and is referenced relative to the share/site folder of the package.