Merge pull request #68 from dvklopfenstein/dox

dvklopfenstein · web-flow · commit 911e373ad11a · 2025-07-15T14:08:44.000-04:00
Added documentation
diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml
@@ -3,10 +3,14 @@ site_url: https://dvklopfenstein.github.io/timetracker/
 docs_dir: source
 site_dir: ../../site
 theme:
+  #name: mkdocs
   name: readthedocs
   custom_dir: docs_theme
   static_templates:
       - index.html
+  #palette:
+  #  scheme: slate
+  #  primary: green
 watch:
   - source
   - docs_theme
@@ -15,6 +19,8 @@ extra_css:
     - assets/colors.css
     - assets/theme.css
     - assets/highlight.css
+#extra_templates:
+#  - sitemap.xml
 markdown_extensions:
   - admonition
 repo_url: https://github.com/dvklopfenstein/timetracker/
@@ -32,6 +38,7 @@ nav:
     - Basic Usage: usage_basic.md
     - Advanced Usage: usage_advanced.md
     - Pandas: pandas.md
+    - Invoicing: invoicing.md
   - 'Reference':
     - Global configuration File: config_global.md
   - 'Community':
diff --git a/doc/mkdocs/sitemap.xml b/doc/mkdocs/sitemap.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/config_global/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/config_local/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/contributing/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/installation/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/invoicing/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/overview/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/pandas/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/reference-command-line/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/tips-and-tricks/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/usage_advanced/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+    <url>
+         <loc>https://dvklopfenstein.github.io/timetracker/usage_basic/</loc>
+         <lastmod>2025-06-13</lastmod>
+    </url>
+</urlset>
diff --git a/doc/mkdocs/source/BingSiteAuth.xml b/doc/mkdocs/source/BingSiteAuth.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0"?>
+<users>
+	<user>BAB0C9F21E51CAD68E6B0385C807FBE2</user>
+</users>
diff --git a/doc/mkdocs/source/google2188449bc9879cec.html b/doc/mkdocs/source/google2188449bc9879cec.html
@@ -0,0 +1 @@
+google-site-verification: google2188449bc9879cec.html
diff --git a/doc/mkdocs/source/index.md b/doc/mkdocs/source/index.md
@@ -3,42 +3,70 @@ Copyright (C) DV Klopfenstein, PhD
 License: https://www.gnu.org/licenses/agpl-3.0.en.html#license-text
 https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup
 -->
-# Timetracker-csv
-[![PyPI - Version](https://img.shields.io/pypi/v/timetracker-csv)](https://pypi.org/project/timetracker-csv)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14803225.svg)](https://doi.org/10.5281/zenodo.14803225)
-![GitHub License](https://img.shields.io/github/license/dvklopfenstein/timetracker)
+<p align="center" style="display:inline">
+<h1 align="center">Timetracker-csv</h1>
+<h3 align="center">Pandas-friendly time tracking from the CLI, repo by repo</h3>
+<h3 align="center">
+<a href="https://pypi.org/project/timetracker-csv"><img src="https://img.shields.io/pypi/v/timetracker-csv" alt="PyPI - Version"></a> |
+<a href="https://doi.org/10.5281/zenodo.14803226"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.14803226.svg" alt="DOI"></a> |
+<a href="https://www.gnu.org/licenses/agpl-3.0.en.html"><img src="https://img.shields.io/github/license/dvklopfenstein/timetracker" alt="License"></a>
+</h3>
+<pre align="center" style="font-family: monospace; font-size: larger; border: 1px solid #ccc; padding: 10px; display: inline-block;">
+┌────────────────────────────┐
+│ 🕒 Timetracker CLI Tool    │
+│ Track time → CSV → pandas  │
+└────────────────────────────┘
+</pre>
+</p>
 
 Track time spent on multiple projects,
 one repo at a time from the [CLI](https://blog.iron.io/pros-and-cons-of-a-command-line-interface)    
 
 Time is saved in
-[pandas](https://pandas.pydata.org/pandas-docs/stable/index.html)-friendly
+[pandas](https://pandas.pydata.org/pandas-docs/stable/index.html)-friendly plaintext
 [CSV](https://www.datarisy.com/blog/understanding-csv-files-use-cases-benefits-and-limitations) files
 
 <p align="center"><img src="https://github.com/dvklopfenstein/timetracker/raw/main/doc/mkdocs/source/images/stopwatch.png" alt="timetracker" width="750"/></p>
 
+## Description
+Timetracker is a
+lightweight, privacy-respecting CLI tool
+that logs your work sessions into
+clean, pandas-friendly CSV files.
+Whether you're juggling multiple projects or
+just want a no-fuss way to monitor your productivity,
+Timetracker keeps your data local, editable, and analysis-ready.
+* No cloud. No surveillance.
+* Human-readable logs perfect for Python and pandas workflows.
+* Quick to set up, easy to use, and fully open source.
+* Supports free-form messages, optional activity types, and tag metadata
+
 ## Quickstart
-The `name` used by this time tracker is determined
-by the `USER` environmental variable by default.
-In this example, the username is "bez."
+The username of the researcher running this timer is "bez."
+The project repository (repo) name is "meetinghouse."
 ```sh
 #----------------------------------------------------
 # 1) Initialize a timetracker project
-$ cd /home/bez/meetinghouse
+$ cd /home/bez/projs/meetinghouse
 
-$ trk init
-Initialized timetracker directory: /home/bez/meetinghouse/.timetracker
+$ trk init --csvdir doc/
+Initialized timetracker directory: /home/bez/projs/meetinghouse/.timetracker
 
 #----------------------------------------------------
 # 2) Start the timer
 $ trk start
 Timetracker started now: Mon 09:00 AM: 2025-03-24 09:00:00
+```
 
+Initializing with the option `--csvdir doc/` will cause time units to be written to
+a csv file stored in the `doc/` directory,
+rather than in the default repo root directory.
+```sh
 #----------------------------------------------------
 # 3) Stop the timer
 $ trk stop -m 'Received instructions'
 Timer stopped at Mon 2025-03-24 12:00:00 PM
-Elapsed H:M:S 0:03:00 appended to timetracker_meetinghouse_bez.csv
+Elapsed H:M:S 0:03:00 appended to doc/timetracker_meetinghouse_bez.csv
 
 #----------------------------------------------------
 # 4a) Report my time units for this project
@@ -47,7 +75,7 @@ Day  Date        Span     Total  Description
 Sun  2025-03-24  03:00    03:00  Received instructions
 
 #- - - - - - - - - - - - - - - - - - - - - - - - - - 
-# 4b) You can also get the total hours that you spent on a project:
+# 4b) Get my total hours spent on the project:
 $ trk hours
 0:03:00 H:M:S or 3.000 hours
 ```
diff --git a/doc/mkdocs/source/installation.md b/doc/mkdocs/source/installation.md
@@ -26,7 +26,7 @@ $ cd /home/bez/projects/meetinghouse
 $ trk init
 Ran `git add .timetracker/config .timetracker/.gitignore`
 Initialized project directory: /home/bez/projects/meetinghouse/.timetracker
-Added project to the global timetracker config: /home/dvklo/.timetrackerconfig:
+Added project to the global timetracker config: /home/bez/.timetrackerconfig:
   project: meetinghouse; config: /home/bez/projects/meetinghouse/.timetracker/config
 ```
 ### 2) Start the timer
diff --git a/doc/mkdocs/source/invoicing.md b/doc/mkdocs/source/invoicing.md
@@ -0,0 +1,31 @@
+# Invoicing
+
+----------------------------------------------------------------------------------
+## Quickstart invoicing
+### Mark timeslots as `Billable`
+To mark an item as billable, use the `--billable` or `-b` option in the `stop` command:
+```sh
+$ trk start
+Timetracker started at: Wed 08:00 AM: 2025-06-04 08:00:00
+
+$ trk stop --billable --message "Defined meetinghouse project goals, budget, and timeline"
+or
+$ trk stop -b -m "Defined meetinghouse project goals, budget, and timeline"
+Timetracker stopped at: Wed 2025-06-04 05:00:00 PM: 2025-06-04 17:00:00
+Elapsed H:M:S 9:00:00 appended to timetracker_meetinghouse_bez.csv
+```
+
+### Get an invoice of billable items
+All items `tag`ed with `Billable` will be included in the invoice:
+```sh
+```
+
+----------------------------------------------------------------------------------
+## Advanced invoicing
+To create an invoice for a project while the current working directory
+is not in the time-tracked repo, use the `--trk-dir` option:
+```sh
+$ trk --trk-dir ../antimicrobial_stewardship/.timetracker/ invoice
+  WROTE: report.docx
+```
+
diff --git a/doc/mkdocs/source/usage_advanced.md b/doc/mkdocs/source/usage_advanced.md
@@ -3,24 +3,27 @@ Under construction...
 
 
 ## Initialize a project
-To begin, initialize your project for timetracking:
+To begin, initialize your project for timetracking with `trk init`:
 ```sh
 # Initialize project for timetracking
 $ trk init
 Ran `git add .timetracker/config .timetracker/.gitignore`
 Initialized project directory: /home/bez/projects/meetinghouse/.timetracker
-Added project to the global timetracker config: /home/dvklo/.timetrackerconfig:
+Added project to the global timetracker config: /home/bez/.timetrackerconfig:
   project: timetracker; config: /home/bez/projects/meetinghouse/.timetracker/config
 ```
 
 ### Initializing runs `git add`
-If the project is git-managed, timetracker runs:
-`git add .timetracker/config .timetracker/.gitignore`.
+If the project is git-managed, timetracker runs
+`git add .timetracker/config .timetracker/.gitignore`,
+which adds these timetracker files to your project's git repo:    
+  * `.timetracker/config`
+  * '.timetracker/.gitignore'
 Use the `--no-git-add` option inhibit running `git add`.
 ```sh
 $ trk init --no-git-add
 Initialized project directory: /home/bez/projects/meetinghouse/.timetracker
-Added project to the global timetracker config: /home/dvklo/.timetrackerconfig:
+Added project to the global timetracker config: /home/bez/.timetrackerconfig:
   project: timetracker; config: /home/bez/projects/meetinghouse/.timetracker/config
 ```
 
diff --git a/doc/mkdocs/source/usage_basic.md b/doc/mkdocs/source/usage_basic.md
@@ -4,22 +4,19 @@ License: https://www.gnu.org/licenses/agpl-3.0.en.html#license-text
 -->
 
 # Basic Usage #
-**Timetracker-csv** tracks time one project repository at a time.
+**Timetracker-csv** tracks time one project repository (repo) at a time.
 
 For a list of **timetracker-csv** commands, enter `trk --help`.
 
 ## Projects ##
-A project repository is a directory that contains
-project files and project sub-directories.
-
 **Timetracker-csv** works seemlessly
 with projects that are version-managed with `git`.
 But it also works with any project.
 
-If you use `git`, then each git-managed project repository
+If you use `git`, then each git-managed project repository (repo)
 will also be a trk-managed project.
 This means that time will be saved in separate
-CSV files for separate projects.
+CSV files for separate repos.
 
 Multiple CSV files can be combined
 into a single CSV file
@@ -75,7 +72,7 @@ To begin, initialize your project for timetracking:
 $ trk init
 Ran `git add .timetracker/config .timetracker/.gitignore`
 Initialized project directory: /home/bez/projects/meetinghouse/.timetracker
-Added project to the global timetracker config: /home/dvklo/.timetrackerconfig:
+Added project to the global timetracker config: /home/bez/.timetrackerconfig:
   project: timetracker; config: /home/bez/projects/meetinghouse/.timetracker/config
 ```
 
@@ -174,7 +171,6 @@ $ timestr "2025-03-01T15:55-04:00"
 ```
 
 ### Track your time
-
 Use the `start` and `stop` commands to record time:
 ```sh
 $ trk start --at 9am
@@ -217,6 +213,45 @@ Mon  2025-03-31  00:30    05:30  Began crafting a chest from Acacia wood to stor
 Mon  2025-03-31  02:00    07:30  Covered chest in gold
 ```
 
+## Show running timers
+Show all timers that are currently running in either
+the default concise format or the verbose format.
+
+### Concise format
+Bez is the researcher whose username is `bez`.
+Bez is currently working on three projects:
+`architecture`, `stonecutting`, and `cabinetry`.
+
+The command, `trk running` will show
+the day and time that the timer was started (`Tue 2025-07-15 11:56:17 AM`) and
+the elapsed time in hours, minutes, and seconds (`H:M:S 1:04:45`).
+
+```sh
+$ trk running
+Began Tue 2025-07-15 11:56:17 AM -> H:M:S 1:04:45 by bez for architecture
+Began Tue 2025-07-15 11:35:40 AM -> H:M:S 1:25:22 by bez for stonecutting
+Began Tue 2025-07-15 12:00:00 PM -> H:M:S 1:01:03 by bez for cabinetry
+3 of 37 projects have running timers; listed in: /home/bez/.timetrackerconfig
+```
+
+### Verbose format
+Using `--verbose` will show the directory for each project that has a running timer.
+In this example, each project directory is in the `/home/bez/projs/` directory.
+```sh
+$ architecture running -v
+Began Tue 2025-07-15 11:56:17 AM -> H:M:S 1:06:35 by bez for architecture
+    /home/bez/projs/architecture
+
+Began Tue 2025-07-15 11:35:40 AM -> H:M:S 1:27:12 by bez for stonecutting
+    /home/bez/projs/stonecutting
+
+Began Tue 2025-07-15 12:00:00 PM -> H:M:S 1:02:53 by bez for cabinetry
+    /home/bez/projs/cabinetry
+
+3 of 37 projects have running timers; listed in: /home/bez/.timetrackerconfig
+```
+
+
 ## Activities
 There is one `Activity` column in each CSV file.
 For example, to add the activity, `docs`, to a time unit do:
diff --git a/makefile b/makefile
@@ -1,7 +1,10 @@
 MAKEFLAGS := --no-print-directory
 
 PYTHON := python3
-CSV := /home/dvklo/timetrackers/timetracker_trk_dvklo.csv
+CSV := ~/timetrackers/timetracker_trk_dvklo.csv
+
+dox:
+	find doc/mkdocs
 
 install:
 	pip install .
@@ -70,9 +73,6 @@ csv:
 hours:
 	trk --trk-dir $(DIRTRK) hours
 
-docx:
-	trk --trk-dir $(DIRTRK) report -o $(CSV) -o timetracker.docx
-
 	
 files:
 	@grep -nH --color filename $(DIRTRK)/config

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+google-site-verification: google2188449bc9879cec.html`