Colberto Tremblay
Software to control Colberto
|
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
conda create -n colberto_mybranch
or the Anaconda GUI interface and active it conda activate colberto_mybranch
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.which python
in Linux or where python
in Windows and import it into your IDE (e.g. VCode with Python pluggin) 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.
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:
/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 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 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()