Skip to content

Latest commit

 

History

History
81 lines (59 loc) · 4.74 KB

class.generation.rst

File metadata and controls

81 lines (59 loc) · 4.74 KB
Raw

Class generation

Why do we generate our class

The class files are very complex but very similar. The only things that deferred from one class to another are the properties and methods. So every class file is a copy/paste/adapt of a template. To avoid doing this by hand (which would be time consuming and source of errors), we have created a “code generator” that read our documentation and automatically write the class files according to our template. That way to add a new properties to a class, change a maximum, rename a method… The only thing needed is to update the documentation and run the generation process.

How is the documentation organized

As there are many classes in PYLEECAN, we have created some group to sort them. For instance the group “Slot” contains every single slot related class. We have created a reference CSV file for each class. They all follow the same logic and contains all the information about the corresponding class. The name of the CSV file is the name of the corresponding class.

Each CSV file contains one sheet with two tables:

_static/table1.png

The first table is for the properties of the class. Each line of this table is a property and its related information. Note that the order of the column is the same in all the documentation to allow the generation. If you need to add a new column or change the order, you will need to adapt the value inside Generator.read_fct.py to make sure that the generator will still work.

Here are the meaning and the use of the column:

  • Variable name: The name of the property to create in the object. It must be in English and follow the python naming rules
  • Unit: This field is for documentation only and is not used in the generation
  • Description (EN): We use this definition to create the help text of every property of our object. Please make sure that there always are a definition (even if the property name is clear). For description on several lines, use n in the description text.
  • Description (FR): Unused but one day could be used to generate a French version of PYLEECAN
  • Size: 0 for scalar, 1 for vector, 2 for Matrix… (documentation only)
  • Type: The type of the object. It will be used to check the input data (to prevent the user to provide a string when an integer is needed). You can specify a PYLEECAN class name (even from other group), it will allow the use of this class and any of its inherited classes. For matrix and vector, use “ndarray”. You can also provide: “[Slot]” which allow to specify a list of Slot object for instance.
  • Default Value: You must provide a default value for the __init__ method.
  • Minimum value: You may provide a minimum value for the check, not that the test is <=
  • Maximum value: You may provide a minimum value for the check, not that the test is >=
  • Observation: Internal comment on the property
  • Level: (Internal) importance of the parameter in the machine design (for the GUI design)

The second table is for global class information and methods:

_static/table2.png

  • Package: The name of the group (ie the name of the group which the class belongs e.g: Slot, Material)
  • Inherit: Name of the mother class (even from another group)
  • Methods: Name of the methods of the class (one line by method, in alphabetic order)
  • Constante Name / Value: To add constant to the class (one line by constant)
  • Description classe: Help text of the class
  • Classe Fille: List of all the class that inherit this one (one line by class)

Class creation

To add a class, the only thing to do is to create an CSV file named with the class name and fulfilled with the two tables in :ref:`class.generation:How is the documentation organized`. The CSV file created will be added in /Generator/ClassesRef/<Group>/ with the right group name and finally call the class generator.

Generated code

You will find the generated classes in /Classes/.The code generated in each class is:

  • automatic import of all the class method from /Methods/<Group>/class_name/
  • init() method,
  • the method to convert the class to string
  • the method to convert the class to a dictionary
  • the getter and setter of each property. The setter checks the type, min and/or max of the user input value before setting the property
  • automatic docstring is also added following the CSV documentation so that the user can have inline help.

If you want to go much further in understanding the class generation process:

.. toctree::
    :maxdepth: 2

    generation.process