Software Development – Page 13

SnakeMD is one of those projects I put together for myself that has sort of outgrown my own use. As a result, I figured it was time to start documenting its growth. What Are Checklists? If you're familiar with Markdown, you probably already know the syntax to create a list. In general, there are two types of list syntaxes: ordered and unordered. They look like this: - This - is - an - unordered - list 1. This 2. is 3. an 4. ordered 5. list Naturally, these lists render as follows: This is an unordered list This is an ordered list Now, as it turns out, some flavors of Markdown (or possibly all, I'm not sure) support checklists. To create a checklist, we take the syntax of the unordered list (though I believe this works in either cases) and add a set of square brackets to it as follows: - [ ] This - [ ] is - [ ] a - [ ] checklist Checklists are pretty cool because you can also mark the individual checkboxes as completed: - [ ] This - [x] is - [ ] a - [x] checklist And you'll get something that looks like this (thanks, GitHub): This is a checklist In this update, one user, Bass-03, added this feature, so now you too can add checklists to your Python code as follows: import snakemd doc = snakemd.new_doc("README") doc.add_checklist( [ "Pass the puck", "Shoot the puck", "Score a goal" ] ) And of course, the update includes various ways to create these lists. For example, you can use the new MDCheckList object to control whether or not the items start checked or unchecked. Similarly, you can use the new CheckBox object to control the checked status of individual items. Why Add Checklists? There are basically two main reasons you might add checklists to a Markdown generation package. First, you might include checklists because checklists are a fairly standard feature in Markdown. At the very least, it's a feature that's supported in GitHub markdown which is a tool that I use often. Second, you might include checklists because you have a personal need for the feature. Here's what Bass-03 is planning to use the feature for: Just as background, I am going to use this package to turn a todoist export to markdown, so I can import it into taskade. Final product will be Todoist Projects turned into Markdown, which could be used on any markdown editor of course. Project here https://gitlab.com/mundo03/todoist-export GitHub Comment Certainly, I'm starting to think of ways this feature might be useful. How Do Checklists Work? For those of you interested in how checklists work under the hood, it's helpful to understand how the package is designed. At its core, SnakeMD is an object-oriented script which leverages objects for each of the type of elements you can add to a Markdown file. For example, the library features objects for paragraphs, tables, and lists. Now, when I was originally designing the library, I wanted to make it as easy to use as possible. As a result, the objects aren't the central focus of the package. Instead, I have a new_doc() function which is used to generate the Document object. From there, Document supports dozens of methods for creating the various elements you might want in a Markdown document. The reason for designing the package this way is pretty simple. Objects in Python are a pain to use! For example, without the handy methods defined in Document, you would have to import a separate class every time you need it. With the current design, you just need to import snakemd and the implicit Document object will give you all the functionality you probably need. If you're unconvinced of this design, no worries! I happen to like it because it's very similar to the express library provided by Plotly. If you want a bar graph but don't care about all the ways you might customize it, just dump your dataframe into the express bar plot function. The same idea applies with SnakeMD. With that out of the way, let's talk about how checklists work. First, checklists are essentially MDLists under the hood. After all, the only difference between a checklist and an unordered list are the square brackets. The way Bass-03 designed the change was to create a new class called MDCheckList that extends MDList. It would then render the items according to the rules of MDList while inserting those square brackets where needed. Of course, the drawback of this design is granularity. In short, you don't really have control over whether or not each item is checked. As a result, Bass-03 included a CheckBox object which could be used in combination with an MDList to inject the checkboxes. Finally, I wrapped the MDChecklist class into the add_checklist() method to allow folks to quickly create checklists from a list of items. Plans for the Future? Now that the checklists are a part of the package, I was able to include an example in the main README. Beyond that, the only changes are in the documentation, which pull from the package directly. Looking forward, I don't have a lot of immediate plans for the library. In general, I'm just happy that people are using it. If you're interested in helping out yourself, check out the list of issues. Otherwise, here are some other things I've been working on: How to Generate Markdown in Python Using SnakeMD Write a Python Script to Autogenerate Google Form Responses The Sample Programs READMEs Now Feature Missing Solutions As always, thanks again for checking out the site!