Commit f65903ec authored by Genial-O's avatar Genial-O
Browse files

merge(dev): release 18.0.0

parents d3157d8c 4d876b45
image: alpine
stages:
- sheldon
- lint
- build
- deploy
sheldon-mr:
image: ${DOCKER_ENVDEV_CLANG6}
stage: sheldon
script:
- export ORIG_BRANCH_COMMIT_SHA=$(git merge-base dev origin/${CI_COMMIT_REF_NAME})
- git -c http.sslVerify=false clone --depth 1 https://gitlab-ci-token:${CI_JOB_TOKEN}@git.ircad.fr/Sight/sight-git.git
# Execute sheldon, on all commits from the merge request
- sight-git/hooks/sheldon ${ORIG_BRANCH_COMMIT_SHA}..${CI_COMMIT_SHA}
sheldon:
image: ${DOCKER_ENVDEV_CLANG6}
stage: sheldon
script:
- git -c http.sslVerify=false clone --depth 1 https://gitlab-ci-token:${CI_JOB_TOKEN}@git.ircad.fr/Sight/sight-git.git
- sight-git/hooks/sheldon HEAD^ HEAD
except:
- dev
- master
rst-lint:
image: python:3
stage: lint
script:
- pip install doc8 Pygments
- doc8 --max-line-length 120
markdown-lint:
image: node:alpine
stage: lint
script:
- npm install -g markdownlint-cli
- echo {\"MD013\":{\"line_length\":120}} > .markdownlint.json
- markdownlint --config .markdownlint.json .
doxygen:
image: python:3
stage: build
script:
- pip install sphinx sphinx_rtd_theme
- apt-get update && apt-get install -yqq make
- make html
artifacts:
name: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG"
paths:
- $CI_PROJECT_DIR/_build/html/
pages:
stage: deploy
dependencies:
- doxygen
script:
- apk --no-cache add py2-pip python-dev
- pip install sphinx sphinx_rtd_theme
- apk --no-cache add make
- make html
- mv _build/html/ public/
- mv _build/html/ public/
artifacts:
paths:
- public
only:
- dev
Please read this!
Before opening a new issue, verify the issue you're about to submit isn't a duplicate.
Please remove this notice if you're confident your issue isn't a duplicate.
------
### Summary
(Summarize the bug encountered concisely)
......@@ -41,4 +33,4 @@ logs, and code as it's very hard to read otherwise.)
(If you can, link to the line of code that might be responsible for the problem)
/label ~bug
/label ~Type:bugfix
Please read this!
Before opening a new issue, verify the issue you're about to submit isn't a duplicate.
Please remove this notice if you're confident your issue isn't a duplicate.
------
### Description
(Include problem, use cases, benefits, and/or goals)
......@@ -24,4 +16,4 @@ Please remove this notice if you're confident your issue isn't a duplicate.
During implementation, this can then be copied and used as a starter for the documentation.)
/label ~feature
/label ~Type:feature
......@@ -20,3 +20,11 @@
- [ ] Build on Windows
- [ ] ...
## Associated Issues/Merge Requests
- Issues
- Fixes repo#number
- Merge requests
- repo!number
......@@ -5,10 +5,10 @@ Coding style
.. toctree::
:maxdepth: 2
src/terminology
src/generalities
src/cpp-style
src/documentation
src/xml-style
src/cmake-style
src/license
src/01-terminology
src/02-generalities
src/03-cpp-style
src/04-documentation
src/05-xml-style
src/06-cmake-style
src/07-license
......@@ -3,9 +3,11 @@ Terminology
- Rules are mandatory. Any rule can be (exceptionally) exceeded, but if so, it has to be rigorously justified.
- Recommendations are optional.
- **Camel case** is the practice of writing compound words or phrases such that each word or abbreviation begins with a capital letter. In programming languages, **camel case** is assumed to start with a lowercase letter. We will use the term **upper camel case** when it starts with a capital.
- **Camel case** is the practice of writing compound words or phrases such that each word
or abbreviation begins with a capital letter. In programming languages, **camel case** is assumed to start
with a lowercase letter. We will use the term **upper camel case** when it starts with a capital.
.. code-block :: cpp
camelCaseLabel
UpperCamelCaseLabel
\ No newline at end of file
UpperCamelCaseLabel
Generalities
==============
.. rule :: Preferred language
English is the preferred language for types, variables, functions naming, and code comments.
.. rule :: Maximum size of a line
......@@ -10,4 +10,4 @@ Generalities
.. rule :: Indentation
Use only spaces, and an indent level has four spaces.
Use only spaces, and an indent level has four spaces.
......@@ -9,11 +9,11 @@ Source and files
Source files must be placed in a folder ``src/``. Public header files must be placed in a folder ``include/``. Private headers may be placed in a different location.
.. rule :: Files hierarchy
The file hierarchy should follow the namespace hierarchy. For instance, the implementation of a class ``::ns1::ns2::SService`` should be put in ``src/ns1/ns2/SService.cpp``.
.. rule :: Files extensions
Header files use the extension ``.hpp``.
Implementation files use the extension ``.cpp``.
......@@ -25,7 +25,7 @@ Source and files
It is recommended to declare (or to implement) only one class per file. However tiny classes may be declared inside the same file.
.. rule :: Includes
Use the right include directive depending on the context. ``#include "..."`` must be used to import headers from the same module, whereas ``#include <...>`` must be used to import headers from other modules.
.. rule :: Include path
......@@ -35,7 +35,7 @@ Source and files
.. rule :: Protection against multiple inclusions
You must protect your files against multiple inclusions. To this end, use ``#pragma once`` .
.. code-block :: cpp
#pragma once
......@@ -50,7 +50,7 @@ Source and files
class Foo
{
public:
public:
std::string m_string;
}
......@@ -74,7 +74,7 @@ Source and files
// Header.hpp
class Foo
{
public:
public:
std::string m_string;
}
......@@ -157,7 +157,7 @@ Naming conventions
.. rule :: Function and method names
Functions and methods names must be written in camel case.
Functions and methods names must be written in camel case.
.. recommendation :: Correct naming of functions
......@@ -183,17 +183,17 @@ Naming conventions
static int s_staticVar;
.. rule :: Constant
Static constant variables must be written in snake_case but in capitals, and follow the previous rule.
.. code-block :: cpp
class SampleClass
{
static const int s_AAA_BBB_CCC_VALUE = 1;
static const int s_AAA_BBB_CCC_VALUE = 1;
};
.. rule :: Type
Type names, like classes, must be written in upper camel case.
......@@ -215,7 +215,7 @@ Naming conventions
};
.. rule :: Macro
Macros without parameters must be written in capitals. On the contrary, there is no specific rule on macros with parameters.
.. code-block :: cpp
......@@ -317,7 +317,7 @@ Blocks
The keywords ``public``, ``protected`` and ``private`` are not indented, they should be aligned with the keyword ``class``.
.. code-block :: cpp
class Sample
{
public:
......@@ -368,7 +368,7 @@ Class declaration
{
...
}
.. recommendation :: Separate template class function definition
In addition of the previous rule, you may put the definition of the function in a ``.hxx`` file. This file will be included in the implementation file right after the header file (the compile time will be reduced comparing with an inclusion of the ``.hxx`` in the header file itself).
......@@ -378,25 +378,49 @@ Class declaration
#include <namespaceA/file.hpp>
#include <namespaceA/file.hxx>
Initializer list
~~~~~~~~~~~~~~~~~~~~~~~~~
In-class member initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rule :: One initializer per line
.. rule :: Favor initializion of member variables in-class at declaration.
In a class constructor, use the initialization list as much as possible. Place one initializer per line. Constructors of base classes should be placed first, followed by member variables. Do not specify an initializer if it is the default one (empty std::string for instance).
You should favor in-class initialization for your member variables as shown below.
.. code-block :: cpp
class SampleClass
{
SampleClass();
~SampleClass();
int m_value {0};
bool m_condition {true};
std::string m_string {"Hello World!"};
};
.. rule :: Avoid constructor initialization
Constructor initialization should be avoided, only constructor parameters should be initialized here.
It is possible however to override default in-class initializations on your constructor.
.. code-block :: cpp
SampleClass::SampleClass( const std::string& name, const int value ) :
BaseClassOne( name ),
BaseClassTwo( name ),
m_value( value ),
m_misc( 10 )
m_string ( "Goodbye World!" )
{}
.. rule :: One initializer per line in constructor initialization
In a class constructor, place one initializer per line. Constructors of base classes should be placed first, do not specify an initializer if it is the default one (empty std::string for instance).
.. recommendation :: Align everything that improves readability
To improve readability, you may align members on one hand and argument lists on the other hand.
To improve readability, you may align members on one hand and argument lists on the other hand.
.. code-block :: cpp
......@@ -405,7 +429,9 @@ Initializer list
BaseClassTwo ( name ),
m_value ( value ),
m_misc ( 10 )
{}
{}
Functions
~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -415,7 +441,7 @@ Functions
Whenever possible, use constant references to pass arguments of non-primitive types. This avoids useless and expensive copies.
.. code-block :: cpp
void badFunction( std::vector<int> array )
{
...
......@@ -428,7 +454,7 @@ Functions
.. recommendation :: Constant reference for shared pointers
For performance sake, it is preferable to use ``const&`` to pass arguments of type ``::boost::shared_ptr``. It is only useful to pass the pointer by copy if the pointer can be invalidated by an another thread during the function call. If you have any doubt, it is safer to pass the argument by copy.
For performance sake, it is preferable to use ``const&`` to pass arguments of type ``::boost::shared_ptr``. It is only useful to pass the pointer by copy if the pointer can be invalidated by an another thread during the function call. If you have any doubt, it is safer to pass the argument by copy.
.. rule :: Constant functions
......@@ -449,7 +475,7 @@ Functions
// This is bad
function( fn1(val1 + val2 / 4 ), fn2( fn3( val3 ), val4) );
// This is better
const float res0 = val1 + val2 / 4;
......@@ -484,7 +510,7 @@ Miscellaneous
.. code-block :: cpp
namespace bf = ::boost::filesystem;
.. rule :: Keyword const
......@@ -497,7 +523,7 @@ Miscellaneous
std::vector< const Object* > objectsList;
void func(const Object& param);
.. recommendation :: Keyword auto
......@@ -526,7 +552,7 @@ Miscellaneous
.. rule :: Explicit integer types
When you do need a specific integer size, use type definitions declared in `<cstdint> <http://www.cplusplus.com/reference/cstdint/>`_, for example :
====== ========= ==========
Bits Signed Unsigned
====== ========= ==========
......
......@@ -43,7 +43,7 @@ Example 1 : Bad documentation block
* @exception
*********************************************
* @todo
*********************************************
*********************************************/
Example 2 : Good documentation block
......@@ -100,6 +100,7 @@ Example 3 : Function documentation
*
* This is the long description.
*
*/
After that the signals and slots must be documented in two distinct sections.
......
XML coding
==========
.. rule :: uid name
``uid`` should have a semantic name. They must be written in lower camel case. Don't prefix the uid by `UID` (like `imageUID`). Moreover, avoid ``uid`` like ``myXXXXX`` or ``customXXXXX``.
.. code-block :: xml
<object uid="image" type="::fwData::Image" />
<service uid="imageReader" type="::ioVTK::SImageReader">
<inout key="image" uid="image" />
</service>
Parameters
----------
.. rule :: Core parameters
These parameters are given by launcher services and are capitalized
* ``WID_PARENT``
* ``AS_UID``
.. rule :: Data parameters (object)
Objects ``uid`` should be written in lower camel case.
.. rule :: Other parameters
Non-object parameters: channel, icon path, title, ...
written in capitals.
Configuration
-------------
.. rule :: Configuration documentation
The configuration must be documented.
.. code-block :: xml
<!--
This config opens a window containing the editors managing the ModelSeries: show/hide reconstructions, change the color, ...
Example:
<service uid="..." type="::fwServices::SConfigController">
<appConfig id="ModelSeriesManagerWindow" />
<inout key="modelSeries" uid="..." />
<parameter replace="ICON_PATH" by="my/icon/path.ico" />
<parameter replace="WINDOW_TITLE" by="" />
</service>
Object:
- modelSeries (mandatory): uid of the ModelSeries to manage
Other:
- ICON_PATH (mandatory): window icon
- WINDOW_TITLE(optional): window title
-->
<extension implements="::fwServices::registry::AppConfig">
<!-- ... -->
</extension>
.. rule :: Order
The configuration file must be written following this order:
#. objects
#. GUI (frame, view, toolbar, menu, menubar)
#. actions
#. ConfigLauncher
#. reader/writer
#. editors
#. extractors
#. listener/sender
#. algorithms
#. renderers
#. connections
#. start
#. update
Each section should begin with an XML comment.
.. code-block :: xml
<!-- *************************************************** begin GUI ************************************************* -->
<!-- ... frame, view, toolbar, menu and menubar services ... -->
.. rule :: Align the xml attributes
The XML attributes should be aligned.
.. code-block :: xml
<service uid="cfgNegato1" type="::fwServices::SConfigController">
<appConfig id="3DNegatoWithAcq" />
<inout key="imageComposite" uid="${imageComposite}" />
<inout key="modelSeries" uid="${modelSeries}" />
<inout key="landmarks" uid="${landmarks}" />
<parameter replace="orientation" by="axial" />
<parameter replace="WID_PARENT" by="view_negato1" />
<parameter replace="patient_name" by="${patient_name}" />
<parameter replace="PickingChannel" by="pickerChannel" />
<parameter replace="CrossTypeChannel" by="crossTypeChannel" />
<parameter replace="setSagittalCameraChannel" by="setSagittalCameraChannel" />
<parameter replace="setFrontalCameraChannel" by="setFrontalCameraChannel" />
<parameter replace="setAxialCameraChannel" by="setAxialCameraChannel" />
</service>
.. rule :: Order the objects
The objects should be ordered by type (ref, new and deferred), and by class.
.. code-block :: xml
<object uid="seriesDB" type="::fwMedData::SeriesDB" src="ref" />
<object uid="loadingSeriesDB" type="::fwMedData::SeriesDB" src="ref" />
<object uid="imageRef" type="::fwData::Image" src="ref" />
<object uid="imageSrc" type="::fwData::Image" src="ref" />
<object uid="newSeriesDB" type="::fwMedData::SeriesDB" />
<object uid="selections" type="::fwData::Vector" />
<object uid="currentActivity" type="::fwMedData::ActivitySeries" src="deferred" />
<object uid="computedImage" type="::fwData::Image" src="deferred" />
.. rule :: Comment renderers
Each scene and its adaptors must begin with an XML comment.
.. code-block :: xml
<!-- ************************************************ begin 3Dscene ************************************************ -->
<service uid="3Dscene" type="::fwRenderVTK::SRender">
<!-- ... -->
</service>
<service uid="adaptor1" type="::visuVTKAdaptor::SMesh" />
<service uid="adaptor2" type="::visuVTKAdaptor::SMesh" />
The starts of these adaptors must be preceded by a comment with the scene name
.. code-block :: xml
<!-- ************************************************* begin start ************************************************* -->
<start uid="frame" />
<!-- 3DScene adaptors-->
<start uid="adaptor1" />
<start uid="adaptor2" />
Example
-------
.. code-block :: xml
<!-- ************************************************** begin data ************************************************* -->
<object uid="image" type="::fwData::Image" />
<!-- *************************************************** begin GUI ************************************************* -->
<service uid="frame" type="::gui::frame::SDefaultFrame">
<gui>
<frame>
<name>Application</name>
<icon>Application-@PROJECT_VERSION@/tuto.ico</icon>
</frame>
</gui>
<registry>
<view sid="mainView" start="yes" />
</registry>
</service>
<service uid="mainView" type="::gui::view::SDefaultView">
<gui>
<layout type="::fwGui::CardinalLayoutManager">
<view align="center" />
<view align="bottom" minWidth="400" minHeight="30" />
<view align="bottom" minWidth="40" minHeight="30" />
</layout>
</gui>
<registry>
<view sid="3DScene" start="yes" />
<view sid="sliceEditor" start="yes" />
<view sid="snapshotEditor" start="yes" />
</registry>
</service>
<!-- ************************************************ begin actions ************************************************ -->
<service uid="actionOpenImage" type="::gui::action::SSlotCaller">
<slots>
<slot>imageReader/update</slot>
</slots>
</service>
<!-- ******************************************** begin readers/writers ******************************************** -->
<service uid="imageReader" type="::uiIO::editor::SIOSelector">
<inout key="data" uid="imageUID" />
<type mode="reader" />
</service>
<!-- *********************************************** begin editors ************************************************* -->
<service uid="sliceEditor" type="::uiImageQt::SliceIndexPositionEditor" autoConnect="yes">
<inout key="image" uid="imageUID" />
<sliceIndex>axial</sliceIndex>
</service>
<service uid="snapshotEditor" type="::uiVisuQt::SnapshotEditor" />
<!-- ************************************************ begin 3Dscene ************************************************ -->
<service uid="3Dscene" type="::fwRenderVTK::SRender">
<scene>
<picker id="myPicker" vtkclass="fwVtkCellPicker" />
<renderer id="default" background="0.0" />
<adaptor uid="imageAdaptor" />
<adaptor uid="snapshotAdaptor" />
</scene>
</service>
<service uid="imageAdaptor" type="::visuVTKAdaptor::SNegatoMPR" autoConnect="yes">
<inout key="image" uid="imageUID" />
<config renderer="default" picker="myPicker" mode="3d" slices="3" sliceIndex="axial" />
</service>
<service uid="snapshotAdaptor" type="::visuVTKAdaptor::SSnapshot">
<config renderer="default" />
</service>
<!-- ********************************************* begin connections *********************************************** -->
<connect>
<signal>snapshotEditor/snapped</signal>
<slot>snapshotAdaptor/snap</slot>