From 86b5ad55fde70cb507a511bcdf65cbac5eb79aa8 Mon Sep 17 00:00:00 2001 From: Aurelien Gateau Date: Thu, 31 Oct 2024 09:01:52 +0100 Subject: [PATCH] Add markdown linter, and fix Markdown documents --- .markdownlint.yml | 14 ++++++++++++++ .pre-commit-config.yaml | 5 +++++ doc/bugtracking.md | 12 +++++++----- doc/dev/db-updates.md | 2 +- doc/dev/hacking.md | 2 +- doc/ical.md | 18 +++++++++--------- doc/tips.md | 16 +++++++++------- 7 files changed, 46 insertions(+), 23 deletions(-) create mode 100644 .markdownlint.yml diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 00000000..6a3dc502 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,14 @@ +default: true +ul-indent: + indent: 4 + +fenced-code-language: false + +line_length: false +first-line-h1: false +no-trailing-punctuation: false +no-inline-html: false +commands-show-output: false + +# Changelog files are full of duplicate headers +no-duplicate-header: false diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index febd5ed2..121b8c8b 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -7,6 +7,11 @@ repos: - id: check-yaml - id: check-added-large-files + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.32.2 + hooks: + - id: markdownlint-fix + - repo: local hooks: - id: tests diff --git a/doc/bugtracking.md b/doc/bugtracking.md index 6b929432..ae8826b1 100644 --- a/doc/bugtracking.md +++ b/doc/bugtracking.md @@ -1,11 +1,13 @@ -# Introduction +# Bugtracking + +## Introduction Yokadi comes with a set of commands tailored to help you track bugs. These commands are `bug_add` and `bug_edit`. They are similar to `t_add` and `t_edit` except they will ask you a few questions to help you decide which bug to fix next. -# Entering a bug +## Entering a bug Enter a new bug like you would enter a new task: @@ -48,7 +50,7 @@ If you edit the task with `t_edit 12` you will only be able to fix the task title. To be asked for severity, likelihood and bug id again, use `bug_edit 12`. -# What's next? +## What's next? Based on the severity and likelihood, Yokadi computes the urgency of the bug. The formula used is: @@ -64,7 +66,7 @@ This is based on the concept of "User Pain", as described by Danc here: Now, when you list your tasks with `t_list`, the most urgent tasks will be listed first, making it easy to fix the most important bugs first. -# Behind the scenes +## Behind the scenes Likelihood, severity and bug are stored as Yokadi keywords (Yokadi keywords can be associated with an integer value). @@ -74,7 +76,7 @@ task urgency field. Yes, this means there is duplication and you may get likelihood/severity and urgency out of sync if you manually adjust urgency with `t_set_urgency`. In practice, I found it was not a problem. -# Tricks +## Tricks Here are a few tricks I came up with while using Yokadi to do bug tracking: diff --git a/doc/dev/db-updates.md b/doc/dev/db-updates.md index 0e5ad5cd..36d94953 100644 --- a/doc/dev/db-updates.md +++ b/doc/dev/db-updates.md @@ -8,7 +8,7 @@ The update process goes like this: - Copy yokadi.db to work.db - for each v between x and x + n - 1: - - run `updateto.update()` + - run `updateto.update()` - Create an empty database in recreated.db - Fill recreated.db with the content of work.db - If we are updating the database in place, rename yokadi.db to yokadi-$date.db diff --git a/doc/dev/hacking.md b/doc/dev/hacking.md index 97e466f2..2d49375a 100644 --- a/doc/dev/hacking.md +++ b/doc/dev/hacking.md @@ -81,7 +81,7 @@ Keep import in blocks, in this order: Keep import blocks sorted. It makes it easier to check if an import line is already there. -# Command docstrings +## Command docstrings All commands are documented either through their parser or using the command docstring. To ensure consistency all usage string should follow the same diff --git a/doc/ical.md b/doc/ical.md index b74abd77..d47a3c88 100644 --- a/doc/ical.md +++ b/doc/ical.md @@ -1,4 +1,6 @@ -# Intro +# Ical support + +## Introduction This document presents how to use Yokadi with a third party calendar/todolist application that supports the ical format (RFC2445). @@ -12,7 +14,7 @@ TCP port 9000: yokadid --icalserver --port=9000 -# Read your Yokadi tasks in a third party tool +## Read your Yokadi tasks in a third party tool If your third party tool supports ical format and is able to read it through HTTP, just set it up to read on localhost:8000 (or whatever port you setup) and @@ -24,30 +26,29 @@ If your calendar/todo tool only supports local files: * make a simple shell script that downloads the ical file and put it on your crontab. You can use wget for that: - wget -O yokadi.ical http://localhost:8000 + wget -O yokadi.ical Each Yokadi task is defined as an ical VTODO object. Yokadi projects are represented as special tasks to which included tasks are related. -# Create and update yokadi tasks from a third party tool +## Create and update yokadi tasks from a third party tool On the same TCP socket, you can write tasks with the PUT HTTP method. Only new and updated tasks will be considered. -# Supported third party ical tool +## Supported third party ical tool Yokadi should support any tool which implements RFC2345. But we are not in a perfect world. The following tools are known to work properly with Yokadi ical server: -- Kontact/KOrganizer (4.4) from the KDE Software Compilation +* Kontact/KOrganizer (4.4) from the KDE Software Compilation If you successfully plugged Yokadi with another calendar/todolist tool, please let us now in order to complete this list. - -# Some security considerations +## Some security considerations By default, the ical server only listens on localhost (loopback). You can bypass this restriction with the --listen switch which makes the ical server @@ -64,5 +65,4 @@ restrict who can access to your Yokadi daemon: You have been warned. That's why listening only to localhost (which is the default) is strongly recommended. - diff --git a/doc/tips.md b/doc/tips.md index 2009839b..13e899a9 100644 --- a/doc/tips.md +++ b/doc/tips.md @@ -1,13 +1,15 @@ -# Intro +# Tips + +## Introduction This document presents practical advices on how to get the best out of Yokadi. -# Completion +## Completion Yokadi supports completion of command names, and in many commands it can complete project names. Do not hesitate to try the `[tab]` key! -# Setting up a project hierarchy +## Setting up a project hierarchy You can set up a project hierarchy by adopting a name convention. For example if you want to track tasks related to a program which is made of many plugins, you @@ -20,7 +22,7 @@ For example to list all `fooplayer` related tasks you can use: t_list fooplayer% -# Using keywords +## Using keywords Keywords are great to group tasks in different ways. For example you can create a keyword named `phone`, and assign it to tasks which you must accomplish on @@ -36,13 +38,13 @@ Or even nicer, directly print your list (from the shell): yokadi "t_list @diy_store --format plain" | lp -# Keep track of your meetings +## Keep track of your meetings To track my meetings, I like to use a `meeting` keyword together with an assigned due date. Yokadi ability to add long descriptions to tasks is also handy to associate address or contact information to a meeting task. -# Keep track of tasks you delegate to people +## Keep track of tasks you delegate to people When you delegate a task to someone, add a keyword with its name to the task. So you can check that people really do what they promise to do even if they @@ -56,7 +58,7 @@ To check all task that Bob should have done: t_list --overdue @bob -# Some useful shortcuts +## Some useful shortcuts Yokadi relies on readline library, so you can use very useful readline shortcuts such as: