Post

Lesson 8 - Project Documentation, MarkDown and Tools

Posted Updated
By Tomislav Dukez 8 min read

8.2. Project Documentation

Documentation AI

8.2.1. Why Documentation Is Important

The README.md file is the first file that is visible to others when you push your project to a GitHub repository. It is a great way to introduce your project to others and show them how to use your code. It also helps others understand your project. You can easily say that a README.md is a calling card for your project. It should be a summary of your project and its features.

For many smaller and mid-size project, this is a good enough documentation. For larger projects, it should be accompanied by a detailed documentation. Nevertheless, if we browse through many of the open source projects, we can find that most of them have a good and complete README.md file.

The README.md file is also a great way to document our project from it’s conception to the final product for ourselves. It will happen in the future, that we would return to one of our projects, only to find ourselves reading the code and trying to understand what it does.

8.2.2. MarkDown Syntax

README.md file is written in MarkDown. Markdown is a simple, easy-to-use syntax for formatting text. It is a great way to document our project. We will not got too much into details here. Here is a demonstration of the basic syntax of MarkDown:

Here is the Markdown syntax demonstration in two parts:

Headings

1
2
3

# Heading 1
## Heading 2
### Heading 3

Text Formatting

1
2
3
4
5

**Bold text**
*Italic text*
~~This is strikethrough text.~~

<u>This is underlined text.</u>

Links

1
2
3

[Link to Google](https://www.google.com)
[Link to Google](https://www.google.com "Title of link")

Lists

  • ordered lists
    1
2
3

    1. Item 1
2. Item 2
3. Item 3
  1. Item 1
  2. Item 2
  3. Item 3
  • unordered lists
1
2
3

- Item 1
- Item 2
- Item 3
  • Item 1
  • Item 2
  • Item 3

Code For code quotes we use triple backticks. If we want to have syntax highlighting we can write the name of the coding language immediately after the backticks.

```python print(“Hello, world!”) ```

1

print("Hello, world!")

1
2
3
4
5

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
|----------|----------|----------|
| Cell 4   | Cell 5   | Cell 6   |

1
2

> This is a quote
> That's all folks!

1
2

Term: Definition
:   Description

1
2

<h1>Heading</h1>
<p>This is a paragraph</p>

Example Outputs

Bold text and Italic text are used to emphasize certain words.

This is strikethrough text.

This is underlined text.

Link to Google and Link to Google are used to create links.

1

print("Hello, world!")

The following table shows the structure of a Markdown document:

| Column 1 | Column 2 | Column 3 | |———-|———-|———-| | Cell 1 | Cell 2 | Cell 3 | | Cell 4 | Cell 5 | Cell 6 | —

Quotes

1

> This is a quote

This is a quote

Definition lists are used to define technical terms:

1
2

Term: Definition
:   Description
Term: Definition
Description

Image

1

![Image Text](link-to-the-image)

Image

Finally, HTML code is used to format the text:

1
2

<h1>Heading</h1>
<p>This is a paragraph</p>

Heading

This is a paragraph

8.2.3. How to Write a Good README File for Your GitHub Project

For the documentation, we can have more different md, but the one that is the primary is README.md. When we put that file in the root directory of our project, it is rendered on our GitHub project repo. GitHub automatically converts our headings into working links and it makes it easier to navigate through our project. It also can automatically generate the table of contents.

Here is the list of sections and brief descriptions of each:

1. Introduction A brief description of the project, including its purpose and main features.

2. Overview A high-level overview of the project, including its features, functionalities, and technologies used.

3. Flowchart A visual representation of the project’s workflow, showing the steps involved in using the project.

4. Technologies A list of the technologies and dependencies used in the project, including libraries, frameworks, and tools.

5. Getting Started Step-by-step instructions for getting started with the project, including cloning the repository, installing dependencies, and creating a .env file.

6. Usage Instructions for using the project, including step-by-step guides and configuration options.

7. Changelog A list of significant changes made to the project, including bug fixes, new features, and improvements.

8. Contributing Instructions for contributing to the project, including how to fork the repository, create a new branch, and submit a pull request.

9. License Information about the license under which the project is released, including terms and conditions.

10. Credits Acknowledgments to contributors and sponsors who have helped make the project possible.

11. Links Additional resources and links for more information about the project, including its website, documentation, and social media channels.

8.2.4. Some Auxiliary Resources

8.3. Project Directory Structure

There are different ways how to organise your project and you can check the links above to learn more. For your final project, I would propose the structure below. If the project is small, you can use the same you don’t have to have aux directory.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

.
├── app.py
├── aux
│   ├── end.txt
│   ├── highscores.json
│   ├── highscores.py
│   ├── intro.txt
│   ├── questions.json
│   ├── quiz.py
│   └── retrieve_api.py
├── docs
│   ├── img
│   │   └── image.png
│   └── pdf
│       └── doc.pdf
├── README.md
└── requirements.txt
  • in the project’s root directory (/):
    • app.py - is the main file of your project
    • README.md - is our main project documentation file
    • requirements.txt - contains all the dependencies of your project
  • aux/ - directory, contains auxiliary scripts and data files
  • docs/ - directory, contains documentation files (images, PDFs, etc.)

8.3.2. Importing Modules from different directories

  • Python Import Module From Different Directory

  • general syntax:

    • from directory_name import module_name - import module from a directory. We call then functions by using module_name.function_name()
    • from directory_name.subdirectory_name import module_name - import module from a subdirectory. We call then functions by using module_name.function_name()
    • from directory_name.module_name import function_name - import specific function from a module in a directory
    • from directory_name.module_name import * - import all functions from a module in a directory

If we take into consideration the structure we presented in Recommended Project Structure, we can import modules from a subdirectory this way.

1

import aux.highscores as highscores
  • in this case we need to call functions by using highscores.function_name() or
1

from aux import highscores
  • also, in this case we need to call functions by using highscores.function_name()
  • or
1

from aux.highscores import *
  • in this case we need to call functions by using only function_name()

8.4. Using Screenshots and Screencasts in your documentation

  • Asciinema - a CLI tool to record and share terminal sessions.
  • pyPeek - a terminal-based screen cast tool.

To illustrate functionalities, we can use screenshots and screencasts in the documentation. This is a very easy and effective way to present the project and it’s features.

Let us see what are they:

  • screenshots are image files and stored in docs/img folder
  • screencasts are usually gif files and stored in docs/img folder
  • if they are in a video format, best way is to use YouTube platform and add link to the video. Presenting your project in a video gives you an opportunity to explain your project verbally and, if you wish, in a more visually appealing way (video editing is an important part of this process).

Examples: Asciinema asciicast

pyPeek gif image pyPeek gif image

Image Static Image

Screencast Video

python, lesson
python programming code
This post is licensed under CC BY 4.0 by the author.