README.md

   1 # indicator-lunar-calendar
   2
   3 An application indicator for Unity that displays the current date and time
   4 in lunar calendar.
   5
   6 Copyright (c) 2016-2019 Adrian I Lam <spam@adrianiainlam.tk> s/spam/me/
   7
   8 *Not to be confused with [indicator-lunar][1], which shows attributes and
   9 ephemerides for astronomical objects.*
  10
  11 [1]: https://launchpad.net/~thebernmeister/+archive/ubuntu/ppa
  12
  13 ## Screenshots
  14
  15 ![indicator normal][sc1]
  16 Normal appearance of the indicator
  17
  18 ![indicator menu][sc2]
  19 Menu of the indicator, shown on click
  20
  21 ![indicator with solar term][sc3]
  22 Indicator showing solar term information
  23
  24 Note: The conversion is calculated using timezone UTC+8 (HKT), while the clock
  25 shown above is using timezone UTC+1.
  26
  27 [sc1]: screenshots/sc1.png
  28 [sc2]: screenshots/sc2.png
  29 [sc3]: screenshots/sc3.png
  30
  31 ## Dependencies
  32
  33  - Python 3
  34
  35  - [LunarCalendarPy][lcp] (included as submodule here)
  36
  37    Translated from the JavaScript [LunarCalendar][lc] library by GitHub user
  38    @zzyss86.
  39
  40    [lc]: https://github.com/zzyss86/LunarCalendar
  41    [lcp]: https://adrianiainlam.tk/git/?p=LunarCalendarPy.git;a=summary
  42
  43  - [schedule][schedule]
  44
  45    Used for periodic update of the indicator.
  46
  47    [schedule]: https://pypi.org/project/schedule/
  48
  49  - [dbus-python][dbus]
  50
  51    Detects suspends/hibernates which would cause incorrect timings
  52    used by schedule.
  53
  54    [dbus]: https://pypi.org/project/dbus-python/
  55
  56 This indicator used to be written in JavaScript (node.js) using the
  57 node-gtk package, but it was eventually abandoned, got replaced,
  58 the replacement was abandoned, etc. The situation was a bit too messy
  59 for me so I decided to just rewrite the whole thing in Python, which
  60 would also make installation easier for most standard Ubuntus, and
  61 would use less RAM.
  62
  63
  64 ## Usage
  65
  66  1. Install schedule and dbus-python (`pip install schedule dbus-python`).
  67  2. Clone this repository (`git clone --recurse-submodules git://adrianiainlam.tk/indicator-lunar-calendar.git`).
  68  3. Add the script as a startup application.
  69  4. Run the script manually for the first time. (Alternatively, log out
  70     and log in again.)
  71  5. The indicator should be shown at the top right corner, having an icon
  72     that shows the year and a label that shows the month and date.
  73  6. Clicking on the indicator should result in a menu with more detailed
  74     information including the time.
  75
  76 ## License
  77
  78 This program is released under the MIT License. For the full text of this
  79 license, please refer to the file "indicator-lunar-calendar.py".