diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index dafbe9f..4180741 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,6 +6,9 @@ | Has BC-break | yes/no | License | GNU AGPL-v3 +**Checklist:** +- [ ] I have updated the manpage + diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index f1b49e3..fb04327 100644 --- a/.github/workflows/e2e.yml +++ b/.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 + diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c370ca2..01630d0 100644 --- a/.github/workflows/release.yml +++ b/.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/* diff --git a/.gitignore b/.gitignore index 4480c6d..b338cab 100644 --- a/.gitignore +++ b/.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 diff --git a/.scripts/tests-e2e.sh b/.scripts/tests-e2e.sh index 2f7e93e..2595e86 100644 --- a/.scripts/tests-e2e.sh +++ b/.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 diff --git a/README.md b/README.md index 0fda4a2..904ed78 100644 --- a/README.md +++ b/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/` on Linux, `/Users/` 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. diff --git a/manpage/kosmorro.1.md b/manpage/kosmorro.1.md new file mode 100644 index 0000000..e784524 --- /dev/null +++ b/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. + diff --git a/setup.py b/setup.py index 872ad3e..6cb5fd9 100644 --- a/setup.py +++ b/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',