Create beautiful Python documentation in MkDocs & Material with these five automation steps and pre-commit Git hooks

MkDocs automatically generation documentation
MkDocs automatically generation documentation
An automatically generated function documentation with Google-style docstring in MkDocs

In this story, you will learn how to automatically generate documentation from Python modules with a bit of magic in our custom functions, the package mkgendocs, pre-commit Git hooks, and MkDocs. We will touch upon the following elements

  • Automate type-hints to docstrings
  • Automate docstrings to MkDocs with mkgendocs
  • Automate the documentation of new Python functions
  • Tie everything together in pre-commit Git hooks

MkDocs & Material installation

MkDocs is a static site generator for building project documentation and together with the Material framework, it simply looks gorgeous. First, we need to install a heap of packages in order to use all…


Automatically insert variables types from Python’s type-hints (3.5+) into Google-style docstrings

Type hints to Google-style docstrings
Type hints to Google-style docstrings
From type-hints to docstrings, images by the author.

In this story, you will follow me along a journey to automatically generate Google-style docstrings from Python type-hints. We will be looking at the following elements.

  • Insert type-hints into function docstrings
  • Automation with pre-commit Git hooks

Python Type-hints

Since Python 3.5+, we’ve seen the next generation of code documentation: hinting which variable’s types in function/class arguments and return statements. This enables formatters, linters, and IDE’s to provide runtime support for type-checking.


Use pre-commit Git hooks to automate Python code style with these linting and formatting tools

Framework for pre-commit
Framework for pre-commit
Git protocol with black and flake8 incorporated. Image by lj miranda.

Do you dream of never having to worry about formatting your Python code? In this article, I will share with you how to automate clean coding principles.

  • Formatting your code with black.
  • Pre-commit Git hooks
  • Automating Git formatter hooks in place.

Linting Your Code

Linting is the process of running a quality-control tool that performs a static analysis of source code to check for potential errors.

The style guide for Python is PEP-8. A popular linting tool that verifies adherence to the PEP-8 style guide is flake8. It is pip-installable and can easily be run…


Here are the seven tips and code bites that I use every day in my work as a data scientist.

code bites
code bites
Image by author

In this story, I will share what I use in my day-to-day work and what has helped me improve my code. Check the list below to see if there’s anything new for you!

  • Platform independent directory delimiters
  • Variable unpacking and the _ operator
  • .get instead of [key] for dictionary iterations
  • Loop two iterators with the zip function
  • The power of list comprehensions
  • Multiple assignment with * and **

String formatting with f-strings

Hallelujah! That is what I thought when I learned about the Python 3.6+ update that includes a new way of formatting strings: the Python formatted string literal. …


Use these three built-in modules to format your scripts the Pythonic way.

Photo by the author.

In this article, I’ll show you three scripting conventions and corresponding built-in modules to help better format your Python scripts. These modules are designed to adhere to the DRY (don’t repeat yourself) principle and are there to improve the quality of your code and scripts!

In short, we’ll go over the following three components:

  1. How to parse command-line arguments with argparse.
  2. How to debug with the logging() module instead of print().

Always Use an ifmain

ifmain refers to the last lines of code in a Python script that you often see: if __name__ == "__main__":. When…


How to use, format, and fade “flash” messages in Django, both with page reload and asynchronous JavaScript submission

Code
Code
Photo by the author.

In this article, you will learn how the Django messages framework works and how you can use its power, including a way to fade the messages when submitting forms via JavaScript without reloading the page.


Learn about distributed task queues for making asynchronous API requests

Django, RabbitMQ, and Celery logos
Django, RabbitMQ, and Celery logos
Image by author

What happens when a user sends a request, but processing that request takes longer than the HTTP request-response cycle? What if you’re accessing multiple databases or want to return a document too large to process within the time window? What if you want to access an API, but the number of requests is throttled to a maximum of n requests per t time window?

These are part of the questions that were raised during the data collection process for my master’s thesis. For my research, microposts from Twitter were scraped via the Twitter API. …


How to incorporate the immensely popular JSON data format in Python for storage of textual data.

Image by author

In this story, we’ll look at JavaScript Object Notation or JSON, probably the world’s preferred data-interchange format and a sure-fire upgrade from more traditional file storage options (XML, CSV, TSV).

We’ll cover the basics for creating and loading JSON files, file storage, and newline delimited JSON storage and take a look into a more specific use-case of working with textual data and JSON.

Why JSON

JSON is widely used in web applications as the preferred way to interchange data, especially to and from front-end to back-end middleware.


Image by author

Pair-wise Cohen kappa and group Fleiss’ kappa (𝜅) coefficients for categorical annotations

In this story, we’ll explore the Inter-Annotator Agreement (IAA), a measure of how well multiple annotators can make the same annotation decision for a certain category. Supervised Natural Language Processing algorithms use a labeled dataset, that is often annotated by humans. An example would be the annotation scheme for my master’s thesis, where tweets were labeled as either abusive or non-abusive.

IAA shows you how clear your annotation guidelines are, how uniformly your annotators understood it, and how reproducible the annotation task is. It is a vital part of both the validation and reproducibility of classification results.

Accuracy and F1…


Testing w/ selenium
Testing w/ selenium
Image by author.

A test-driven development cycle is a vital part of the migration process of your Django app to production. Learn the basics of TDD in this brief introduction.

I had learned the hard way that functional parts, such as database operations, log-ins, or registrations break without you noticing. Your users, however, will notice. Testing is a vital part of the production process of and in this story, we’ll briefly introduce how to test your Django application.

This story covers:

  • Introducing Unit Tests
  • Unit Test with Django’s TestCase
  • Introducing Functional Testing
  • Functional Testing the Login Page

Test-Driven Development Cycle

Louis de Bruijn

Data Scientist @ ING | Analytics trainee | Msc Information Science | https://www.louisdebruijn.me

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store