Infusion docs generation cli tool

Infusion is an open-source tool that is used for generation of documentation in your code files. It uses OpenAI gpt-4 model to write comments. It was my project and I wrote it in Python.

GitHub link:
https://github.com/SychAndrii/infusion

explainer.js is an open-source tool that is used to explain code snippets in your code files. It uses Groq models to write comments. It was a project of my teammate @aamfahim and he wrote it in Node.JS

GitHub link:
https://github.com/aamfahim/explainer.js

I am currently enrolled in an open-source course at Seneca Polytechnic, where we were tasked to team up with another person and review each other's code and give some suggestions for improvement using GitHub issues. I am going to describe this process.

Mode of communication

Most of the issues generated for both repositories were done using synchronous communication via Discord call. After that, we talked asynchronously using Discord messages, since there was a difficult issue for me to streamline setup of my project using bash scripts, and calling my teammate every time I needed to test if it works on his machine seemed unnecessary. Testing using Docker containers and WSL Linux sub system on my machine was not the same as testing them on Al's system, and it highlighted important bugs.

Experience of reviewing someone's code

I did not experience anything unusual when reviewing my teammate's code, since I have lots of experience with Node.JS development. I liked creating issues and then immediately suggesting solutions to them though. One problem we had is that we could not figure out a way to allow me put labels on the issues I created, only Al could do it, which was annoying.

Experience of someone reviewing my code

Al suggested a lot of room for improvement, particularly with installation of my CLI tool. When he first forked my repo, it was a requirement for the end users to go and install a particular version of python manually, which is definitely a frustrating task. Additionally, he highlighted other possible improvements for convenient usage of a tool, like introducing .env file so that you don't have to input your API key every time you start the tool. I like getting input on my code from other people because it allows me to grow as a developer and it definitely expands my view of development lifecycle.

Issues during reviewing and testing

Most of the problems we had were with my tool, because Al's CLI program was written in Node.JS and we both have a lot of experience with it. In contrast, both of us don't like Python ecosystem, so we had a lot of troubles interacting with it. When testing Al's repository, I found the docs written in his README to be misleading or confusing to understand, especially the model and api-key options. We had to go through the process of trials and errors to figure out which API keys and models are accepted by his tool. When it came to testing my repository, version of python on Al's system was very outdated (2.7), so he had to install 3.10.6 (version, required to use my tool) manually. However, even then the problems did not end. Even though he installed it, it was still not being recognized by the virtual environment my tool creates with pipenv. After that, we also had frustration with entering the API key required for the usage of my tool every time we started it. Finally, the README docs did not help with the installation. We tried to follow them, but we kept getting errors related to some scripts not being recognized on the PATH. That's when I decided that we need some sort of automation tool that does all the installation for you. One thought I had is to dockerize the application, but then it would require me to somehow map Docker volumes to the output directory and input files specified for my tool, and that would complicate everything twice. Thus, I remembered that a lot of package managers are actually command line tools, and if you install them by cloning a GitHub repo, then you need to set them up by executing some kind of bash setup script. So that was the idea that I decided to implement. Finally, both of us could not figure out a way to assign labels like bug or enhancement to the issues we filed.

Issues I filed

https://github.com/aamfahim/explainer.js/issues/13
https://github.com/aamfahim/explainer.js/issues/12
https://github.com/aamfahim/explainer.js/issues/11
https://github.com/aamfahim/explainer.js/issues/10
https://github.com/aamfahim/explainer.js/issues/9

To summarize the issues I found, they mostly covered cases when options that were written in the README file of this project, did not actually work, or the way they worked was misleadingly described.

Issues that were filed on my repo

https://github.com/SychAndrii/infusion/issues/11
https://github.com/SychAndrii/infusion/issues/10
https://github.com/SychAndrii/infusion/issues/9
https://github.com/SychAndrii/infusion/issues/8

To summarize the issues that were found in my repo, they were mostly related to the convenience of usage of my tool. Additionally, there was one bug when you supplied a file with syntactically correct source code to my tool, and it identified it as a file that does not contain valid source code.

Issues I managed to fix

I fixed all of my issues. All of them took less than 30 minutes to fix, but there was one issue, that took me like 2-3 hours to fix:
https://github.com/SychAndrii/infusion/issues/8

It mind seem weird since enhancement of README file should be easily achievable, but what the first suggestion by Al required me to completely remake the installation process of my tool, which required me to introduce 2 scripts for installation - one for bash and one for Powershell. The problem I could not solve for most of the time was that even though these setup scripts properly installed the needed version of python, this version of python was not passed down to the virtual environment, which you need to enter before using my tool. Eventually, I fixed that though.

What I learned

I have definitely improved my README skills. The way I provided example usage was very confusing for the end user. Additionally, I have finally used bash and powershell languages to do something myself, not for a school assignment, not because it was a requirement, but because I wanted to simplify the process of interacting with my tool. Finally, I decided to face the language I absolutely can't stand - which is python. Working with it was definitely not enjoyable for me, but I think it's essential to be able to use it if you want to find a job today, especially with AI trending.

The above is the detailed content of Infusion docs generation cli tool. For more information, please follow other related articles on the PHP Chinese website!