Contributing to Odak¶
Odak is in constant development.
We shape Odak according to the most current needs in our scientific research.
We welcome both users and developers in the open-source community as long as they have good intentions (e.g., scientific research).
For the most recent description of Odak, please consult our description.
If you are planning to use Odak for industrial purposes, please reach out to Kaan Akşit.
All of the Odak contributors are listed in our
THANKS.txt and added to
CITATION.cff regardless of how much they contribute to the project.
Their names are also included in our Digital Object Identifier (DOI) page.
Contributions to Odak can come in different forms. It can either be code or documentation related contributions. Historically, Odak has evolved through scientific collaboration, in which authors of Odak identified a collaborative project with a new potential contributor. You can always reach out to Kaan Akşit to query your idea for potential collaborations in the future. Another potential place to identify likely means to improve odak is to address outstanding issues of Odak.
odak directory contains the source code.
To add to it, please make sure that you can install and test Odak on your local computer.
The installation documentation contains routines for installation and testing, please follow that page carefully.
We typically work with
If you want to add new code to Odak, please do not hesitate to fork Odak's git repository and have your modifications on your fork at first.
Once you test the modified version, please do not hesitate to initiate a pull request.
We will revise your code, and if found suitable, it will be merged to the master branch.
Remember to follow
numpy convention while adding documentation to your newly added functions to Odak.
Another thing to mention is regarding to the code quality and standard.
Although it hasn't been strictly followed since the start of Odak, note that Odak follows code conventions of
flake8, which can be installed using:
pip3 install flake8
You can always check for code standard violations in Odak by running these two commands:
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
There are tools that can automatically fix code in terms of following standards.
One primary tool that we are aware of is
autopep8, which can be installed using:
pip3 install autopep8
Please once you are ready to have a pull request, make sure to add a unit test for your additions in
test folder, and make sure to test all unit tests by running
If your system do not have
pytest installed, it can be installed using:
pip3 install pytest
Under Odak's source's root directory, you will find a folder named
This directory contains all the necessary information to generate the pages in this documentation.
If you are interested in improving the documentation of Odak, this directory is the place where you will be adding things.
Odak's documentation is built using
At this point, I assume that you have successfully installed Odak on your system.
If you haven't yet, please follow installation documentation.
To be able to run documentation locally, make sure to have the correct dependencies installed properly:
pip3 install plyfile pip3 install Pillow pip3 install tqdm pip3 install mkdocs-material pip3 install mkdocstrings
Once you have dependencies appropriately installed, navigate to the source directory of Odak in your hard drive and run a test server:
cd odak mkdocs serve
If all goes well, you should see a bunch of lines on your terminal, and the final lines should look similar to these:
INFO - Documentation built in 4.45 seconds INFO - [22:15:22] Serving on http://127.0.0.1:8000/odak/ INFO - [22:15:23] Browser connected: http://127.0.0.1:8000/odak/
At this point, you can start your favourite browser and navigate to
http://127.0.0.1:8000/odak to view documentation locally.
This local viewing is essential as it can help you view your changes locally on the spot before actually committing.
One last thing to mention here is the fact that Odak's
docs folder's structure is self-explanatory.
markdown rules, and
mkdocsstrings style is