Colberto Tremblay
Software to control Colberto
Loading...
Searching...
No Matches
Contributing

Documentation

The colberto documentation is a mix between a high-level manual found as Markdown pages (.md) in \manual and API documentation automatically generated from docstrings in the src folder. It is automatically generated by Doxygen and its awesome documentation

Documentation for the main branch can be found here. It is automatically generated whenever you push to the main branch through the instructions contained in ./github/worflow folder. For more information on CI/CD and actions in Github, check out this link

You should also check it out and build it yourself in your own branch by running doxygen doxygen.conf and opening index.html in /docs/. It is also automatically built using Doxygen whenever a branch is pushed to its remote.

You can add manual pages in Markdown format to the manual folder. The index.md page is the main page shown in the documentation. The Doxygen Markdown documentation and how to add pages to Doxygen documentation are useful ressources.

Follow common Python DocStrings guidelines

Setting up your Python environnement

  1. Install miniconda or Anaconda environnement managers
  2. Create a virtual environnement for the Colberto project using conda create -n colberto_mybranch or the Anaconda GUI interface and active it conda activate colberto_mybranch
  3. Navigate to the dependencies folder and update the virtual environnement using conda install --yes --file requirements.txt. Conda will install the packages required for the current branch. You might need to run conda config --add channels conda-forge and conda config --set channel_priority strict to add a channel where some pacakge are available.
  4. You can then locate your environnement using which which python in Linux or where python in Windows and import it into your IDE (e.g. VCode with Python pluggin)

Updating python environnement

When developping new features in your branch, it is very likely that you will need to add python packages. You can do this using conda install packagename. You will then need to update the required package list by naviguating to /dependencies/ and using the command conda list -e > requirements.txt. This will dump your current package list into the file so that the packages will be appended to the project requirements. Don't forget to add requirements.txt to your commit.

Naming Conventions

In this project, we follow standard Python naming conventions to ensure that our code is readable and consistent. Below are the guidelines for naming functions and classes:

Folder structure

  • /dependencies : Put conda dependencies list here
  • /src : This is where the code goes and is further divided into subcategories
    • /src/drivers : Let's put all the driver modules in here e.g. SLM.py or Streising.py etc...
    • /src/gui: Code related to the graphical user interface
    • /src/compute: Code that perform internal various computations such as fitting, computing quantitie etc...
  • /samples : Code showing how to use the different modules using import modulename. Keep same subdirectory structure as /src
  • /docs: The output of doxygen doxygen.conf spits the HTML documentation there. Open the index.html in your browser to view it.
  • /manual: The additional manual pages we write to complement the API doc generated automatically by doxygen.
  • /.github/workflow: Where the Github CI/CD actions are.

Classes

Classes are named using the CamelCase convention. This means that each word within the class name starts with a capital letter and there are no underscores between words. This helps in distinguishing class names from function and variable names.

Examples: ImageGenerator EmployeeRecord

Functions and Methods

Functions and methods are named using the snake_case convention. This means that all letters are in lowercase and words are separated by underscores. This makes function and method names easy to read and understand.

Examples:

  • get_depth()
  • write_image()
  • send_email()