Merge pull request #55 from Deuchnord/update-readme

Update doc, add man page

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,6 +6,9 @@
 | Has BC-break   | yes/no
 | License        | GNU AGPL-v3
 
+**Checklist:**
+- [ ] I have updated the manpage
+
 <!--
     Replace this notice by a short README for your feature/bugfix.
 -->

.github/workflows/e2e.yml

@@ -16,9 +16,13 @@ jobs:
 
     - name: Prepare tests
       run: |
+        sudo apt install ruby
+        sudo gem install ronn
         pip install -U setuptools pip
+        cd manpage && ronn kosmorro.1.md && cd ..
 
     - name: E2E tests
       run: |
         export ENVIRONMENT="CI"
         bash .scripts/tests-e2e.sh
+

.github/workflows/release.yml

@@ -13,6 +13,11 @@ jobs:
       uses: actions/setup-python@v1
       with:
         python-version: '3.7'
+    - name: Setup environment
+      run: |
+        sudo apt update
+        sudo apt install ruby
+        sudo gem install ronn
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
@@ -24,6 +29,8 @@ jobs:
         POEDITOR_API_ACCESS: ${{ secrets.POEDITOR_API_ACCESS }}
         POEDITOR_PROJECT_ID: 306433
       run: |
+        cd manpage && ronn kosmorro.md && cd ..
+
         python .scripts/build/getlangs.py
         python setup.py compile_catalog sdist bdist_wheel
         twine upload dist/*

.gitignore

@@ -9,6 +9,9 @@ package-lock.json
 /kosmorrolib/assets/pdf/*
 !/assets/pdf/*.tex
 
+/manpage/*
+!/manpage/*.md
+
 # Translation files are taken care on https://poeditor.com/join/project/GXuhLpdaoh
 *.mo
 *.po

.scripts/tests-e2e.sh

@@ -92,6 +92,9 @@ assertSuccess "$PIP_BIN install latex" "CI"
 # Dependencies installed, should not fail
 assertSuccess "kosmorro --latitude=50.5876 --longitude=3.0624 -d 27 -m 1 -y 2020 --format=pdf -o /tmp/document.pdf"
 
+# man page
+assertSuccess "man --pager=cat kosmorro"
+
 if [ "$failures" != "" ]; then
     echo -e "\n$failures"
     exit 2

README.md

@@ -50,14 +50,26 @@ Then, run Kosmorro by invoking `pipenv run python kosmorro`.
 
 For comfort, you may want to invoke `pipenv shell` first and then just `python kosmoro`.
 
-## Running Kosmorro
+## Using Kosmorro
 
 Using Kosmorro is as simple as invoking `kosmorro` in your terminal!
 
 By default, it will give you the current Moon phase and, if any, the events that will occur today.
 To get the rise, culmination and set of the objects of the Solar system, you will need to give it your position on Earth: get your current coordinates (with [OpenStreetMap](https://www.openstreetmap.org) for instance), and give them to Kosmorro by invoking it with the following parameters: `--latitude=X --longitude=Y` (replace `X` by the latitude and `Y` by the longitude).
 
-Kosmorro has a lot of available options. To get a list of them, run `kosmorro --help`.
+Kosmorro has a lot of available options. To get a list of them, run `kosmorro --help`, or read its manual with `man kosmorro`.
 
 Note: the first time it runs, Kosmorro will download some important files needed to make the computations. They are stored in a cache folder named `.kosmorro-cache` located in your home directory (`/home/<username>` on Linux, `/Users/<username>` on macOS).
 
+### Exporting to PDF
+
+Kosmorro can export the computation results to PDF files, but this feature requires first that you install some additional dependencies. Before you use this feature, please check these packages are installed:
+
+- **A LaTeX distribution:**
+    - Linux: install TeXLive through your packages manager. Kosmorro just needs the minimal installation, you don't need any extension.
+    - macOS: install [MacTeX](https://www.tug.org/mactex/)
+- **The `latex` Python library:**
+    - Arch Linux: the library is available [on the AUR](https://aur.archlinux.org/packages/python-latex)
+    - Any other systems: install it through PyPI: `pip install latex`
+
+These dependencies are not installed by default, because they take a lot of place and are not necessary if you are not interested in generating PDF files.

manpage/kosmorro.1.md

@@ -0,0 +1,71 @@
+# kosmorro(1) -- a program that computes the ephemerides
+
+## SYNOPSIS
+
+`kosmorro`  
+`kosmorro` [_OPTIONS_]...
+
+## OPTIONS
+
+`-h`, `--help`  
+    show a help message and exit
+
+`--version`, `-v`  
+    show the program version
+
+`--clear-cache`  
+    delete all the files Kosmorro stored in the cache
+
+`--latitude=`_LATITUDE_, `-lat` _LATITUDE_  
+    the observer's latitude on Earth
+
+`--longitude=`_LONGITUDE_, `-lon` _LONGITUDE_  
+    the observer's longitude on Earth
+
+`--day=`_DAY_, `-d` _DAY_  
+    a number between 1 and 28, 29, 30 or 31 (depending on the month); the day you want to compute the ephemerides for, defaults to the current day
+
+`--month=`_MONTH_, `-m` _MONTH_  
+    a number between 1 and 12; the month you want to compute the ephemerides for, defaults to the current month
+
+`--year=`_YEAR_, `-y` _YEAR_  
+    the year you want to compute the ephemerides for; defaults to the current year
+
+`--timezone=`_TIMEZONE_, `-t` _TIMEZONE_  
+    the timezone to display the hours in; e.g. 2 for UTC+2 or -3 for UTC-3
+
+`--no-colors`  
+    disable the colors in the console
+
+`--output=`_OUTPUT_, `-o` _OUTPUT_
+    a file to export the output to; if not given, the standard output is used
+
+`--format=`_FORMAT_, `-f` _FORMAT_  
+    the format under which the information have to be output; one of the following: text, json, pdf
+
+## EXAMPLE
+
+Compute the ephemerides for Lille, France, on April 1st, 2022:
+
+```
+kosmorro --latitude=50.5876 --longitude=3.0624 -d 1 -m 4 -y 2022
+```
+
+Compute the ephemerides for Lille, France, on April 1st, 2022, and export them in a PDF document:
+
+```
+kosmorro --latitude=50.5876 --longitude=3.0624 -d 1 -m 4 -y 2022 --format=pdf --output=file.pdf
+```
+
+## AUTHOR
+
+Written by Jérôme Deuchnord.
+
+## REPORTING BUGS
+
+Please report any encountered bugs on Kosmorro's [GitHub project](https://github.com/Deuchnord/kosmorro).
+
+## COPYRIGHT
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+

setup.py

@@ -38,6 +38,9 @@ setup(
     packages=find_packages(),
     scripts=['kosmorro'],
     include_package_data=True,
+    data_files=[
+        ('man/man1', ['manpage/kosmorro.1'])
+    ],
     install_requires=['skyfield>=1.17.0,<2.0.0', 'tabulate', 'numpy>=1.17.0,<2.0.0', 'termcolor'],
     classifiers=[
         'Development Status :: 3 - Alpha',