With taking on more projects that involve more than just myself, I’ve been working on writing documentation to share the knowledge around a project and store information with relevant tips to the project I’m working on.
While searching for a somewhat easy-to-configure, preferably free solution to documentation hosting, I came across Read the Docs. Read the Docs is a helpful 1free hosting service that works with Github’s version control to create expansive documentation for projects.
To get started, you create a copy of their template on GitHub. Then, I used VSCode to clone the repo I just created from the template. Then, on the Read-the-Docs site, you add the repo to start the site building and set it! Read the Docs’ pages, which are written entirely in reStructuredText and similar to Markdown’s formatting. Coming from no experience, I found it relatively easy to learn, referencing the examples and documentation.
A cool feature is using the branching in Github to create versions of documentation and being able to use Githubs strong suit of version control to make sure if I make mistakes or edits I don’t like, I can quickly narrow down where its source is with the notes I added to each version change in Github.
The free tier is only available for community projects and is Ad-supported. Read more↩︎
I recently covered FreeShow, a software made for presentations in Churches. One of the features that I liked and talked about was the open-source nature of the App. In this case, open-source means having the app’s code publicly available on GitHub, with any changes made, issues, or additions to its Codebase available to read / post.
I noticed while poking around the GitHub page for FreeShow, is a large percentage of the code’s language is written in TypeScript.5
Typescript is similar to Javascript in that it adds to the existing framework of JS with additional checks like types, which ensures the data of a variable is the correct “type” it’s been told it is, making it easier to catch errors. I’ve been learning Javascript through Coursera’s Front-end Web Development course, and even though not explicitly teaching TypeScript, Typescript contains everything Javascript has, just with additional features, making it a more straightforward matter of learning those additional features rather than a whole new language.
With the knowledge of FreeShow’s codebase being primarily of a language I could understand, I decided to fork the repository (forking creates a copy of the repository, which is separated from the main code). I started looking through the code to see how it’s constructed and if I could implement my features into the app, that would be useful.
I also later found this page, which contains all the info they give to devs willing to contribute, like where they need help with apps and how their code is typically structured.
I started with one implementation I would find helpful: a way for the application to track when a song gets “used” and then, with that information, have it pull from the oldest used songs from the current date. The primary use case for this feature would be picking songs for Sunday’s service. The current way we do it with Google Slides is to attach an ID to each slideshow, and as the year goes by, eventually, it adds up to #100. In which case, we start over with Sunday #001’s songs. Making it impossible to select a song we sang last week.
Luckily, FreeShow already has a similar variable implemented to track when a song has been last used, called “used.” With that, I made a simple helper script that attaches to the existing “used” variable, “Chronicle.” Chronicle compares the used date with a reference date like Jan 01, 2024, and returns the day value of that comparison.
export function chronicleShow(timestamp: number) {
const usedDate: number = new Date(timestamp).getTime();
const chronicleRef: number = new Date('2024-01-01').getTime();
const daysDifference = Math.floor((usedDate - chronicleRef) / (1000 * 60 * 60 * 24));
//output example "044" (44th day from chronicleRef)
return daysDifference.toString().padStart(3, '0');
}
In reality, this is a super simple script and hardly took any time, mostly being “inspired” by this post by Javatpoint. The more interesting part of adding a simple feature like this is digging through a full app’s code and figuring out what function is used for what. For example, finding where the “used” cache was getting updated was initially difficult. Still, eventually, I found it in a function called “update” because of a message that gets logged when opening a “show” item, and that message linked to the start of the trial to find the “used” cache update line.
A new concept I’m starting to learn in my Coursera course on React Basics (view post series here) is React “States.” States in React is an interesting way of storing the “state” or current information about a variable or function.
ⓘ As a new topic, I’m still learning how React works. For an actual professional, please refer to a better explanation.
The first example of utilizing state is the “React.useState” hook. To use useState, you assign it to two array values that usually consist of one variable storing the value and another variable to set the value of the state. For example:
import { useState } from 'react';
function exampleApp() {
const [user, setUser] = useState("ezra");
}
First, we import the state hook. Then, in the function, we assign two variables to the useState hook. Inside of the state, it has “Ezra,” which, in this case, sets the default value. If we wanted to add a function to update the state to a value, we could do so as follows:
function updateUser(e) {
setUser(e.target.value);
}
Coursera outlines that you generally want to utilize separate functions to handle events. In this case, we have a function that, when called in combination with an input field, will grab the input’s value (e.target.value). We use the setUser that we already declared earlier.
The complete component example they taught me was:
This creates a page with an H1 element and an Input field. By default, H1 says “Ezra,” but when you type into the input field, it actively changes to what you type.
It is an excellent and useful concept that will probably be used frequently in future React programming. Coursera also outlined a general guideline for creating components, specifically when and when not to use states.
As the name implies, you have Stateless and Stateful components, one without any state declarations and others with state declarations. It goes to the basics of how you want things formatted and makes it much easier to later grab the state of an object by passing it down from a parent to a child component rather than having to reinstate that state in each element.
credit: Coursera.org
States in react go a lot deeper and a lot more complex, but I’m excited to learn more about it.
I’m about two months into my Front End Web Development course, and it’s about time I update.
As of this writing, I’ve completed four out of nine of the certificate program’s courses. Since my last post, I’ve finished “Programming with Javascript,” “Version Control,” and “HTML and CSS in Depth.” I’m currently in the middle of “React Basics.”
Programming with Javascript
So far, this is one of my favorite courses in the program. This is mainly because it’s the only language I never really understood the basics of. It covers the basics from logging into the console to editing and integrating with HTML, how to use event handlers, and editing basic HTML with the console in inspect element.
One of the more significant concepts introduced was OOP or Object-Oriented Programming. OOP is a recommended programming model for developing applications, where some parts of a website are thought of as modules that can be removed, duplicated, and quickly edited for reusability.
For example, instead of writing new code every time you want to show the latest blog post, you can create a reusable template that knows how to do this. Then, whenever you need it, you can use that template to automatically grab and display the newest blog post on any page without having to write the code again. A big part of that is being demonstrated in my current course I’m taking on React Basics.
There’s a much better explanation of how it works and more in-depth here.
Version Control
Version control covers the basics of GitHub. As with Javascript, this course was also informative. I’ve used GitHub occasionally for small projects and downloaded many open-source apps, but I never really understood how to use it and how it works. This course covered creating repositories, forking, branching, and basic terminal commands.
One of the neat things I learned about GitHub that I previously did not know about is the branching system for repositories. In a barebones repository, you have the Main branch, which has the (usually) fully fleshed-out main releases for a project. For example, I’m developing docs for the Drone Project (https://ezraharris.com/category/tech/drone/ series I’m doing on building drones for a drone show). With that, I chose a free template for creating docs called “Read-the-Docs.” Read the Docs has a template with GitHub, which makes it super easy to create a copy from the template page and host it for free using their deployment system. The branching is part of the automatic deployment system; I have two branches in GitHub: a Testing branch and a Main branch. I can make changes to the testing branch that may break the formatting, but that’s not on the main page and won’t affect the primary traffic of users. I can preview edits before pushing the testing branch into the main branch.
GitHub has much better documentation on using branching and managing pull requests here.
HTML and CSS in Depth
This also introduced many new concepts I had no idea were natively possible, like animations, using keyframes for more than just linear animations, and creating super smooth effects with only a couple of lines of code.
At the end of this course, I had to create a basic homepage using the concepts covered in the course. I was given a choice of four clients. I ended up choosing Lucky Shrub. I was provided a basic description with info about the client, logos, and a couple of preparation videos outlining the site’s basic framework I would create.
What made this assignment different from the other courses was the peer-reviewed grading. This is where I had some issues with Coursera. The downside is that they only support uploading HTML and CSS files, for the final project, making it challenging to review my peers’ websites because the links between files and folder structures were strange or because they used images outside of what Coursera provided. In the end, it made for a more complicated grading system than what it needed to be.
I ended up uploading the whole site to a GitHub repository and hosted it on Pages.dev. Cloudflare provides free basic web hosting and testing applications. (You can view my finished site for the project here)
I think it’d be a much easier process if Coursera worked with Pages.dev and/or Github to host the sites for previews instead of the mangled way of downloading and hosting it locally they have now.
Overall, I enjoyed all of the courses, but Javascript and React are quickly becoming the most interesting.
Certificates I’ve earned so far for completing mini-courses
