Skip to content

Latest commit

 

History

History
143 lines (97 loc) · 9.15 KB

docs.md

File metadata and controls

143 lines (97 loc) · 9.15 KB

Документация colligendis

Утитила командной строки colligendis предназначеня для сборки и обработки статистики с различных источников.

На текущий момент поддерживаются следующие ресурсы:

  • корпоративный блог на habr.com.

Принцип работы

На текущий момент поддерживается полуручной режим работы: необходимо вручную выгрузить из панели управления блогов на Хабре файл со статистикой по статьям и скормить его утилите.

Загруженные результаты хранятся в SQLite-базе. Генерация выходного файла осуществляется на базе двух загруженных файлов (по идее, их нужно скачивать раз в неделю, чтобы соблюсти промежутки статистики).

Установка

Скачайте последнюю версию из раздела релизов или соберите актуальную версию из main и положите ее в $PATH.

Команды

Ознакомиться с перечнем основных команды и ключей можно на соответствующей странице документации.

Также можно выполнить любую команду с ключом -h для просмотра докментации прямо в терминале. Например:

$ colligendis 
A command-line utility for obtaining various statistics and reports on it.

Usage:
  colligendis [command]

Available Commands:
  collect     Сollect statistics from loaded sources.
  completion  Generate the autocompletion script for the specified shell
  config      Various utility settings
  help        Help about any command
  load        Load statistics from sources
  view        Displaying various information in the terminal

Flags:
  -h, --help      help for colligendis
  -v, --verbose   Show the full report of the commands

Use "colligendis [command] --help" for more information about a command.

Сбор статистики и просмотр результатов

Работа со статистикой Хабра происходит следующим образом:

  • Скачивается CSV-файл со статистикой по статьям из админки корпоративного блога.
  • Файл загружается в БД утилиты командой load. После этого становятся доступны следующие режимы работы:
    • просмотр статей, авторов и статистики прямо в терминале сответствующей командой view;
    • генерация полной статистики в формате PDF.

    Обратите внимание, что на текущий момент по умолчанию для генерации статистики используется период между двумя последними загрузками статистики с сайта. Например, если первый файл будет за 28 июня (пятницу), а второй за 5 июля (также пятницу), то сгенерируется статистика за неделю с пятницы по пятницу. Эта функиональность в будущем будет расширена для выбора случайных диапазонов.

Рассмотрим на примере.

Загрузка источника с Хабра

Перейдите в раздел «Публикации» личного кабинета корпоративного блога и скачайте там файл CSV со статистикой по статьям:

Загрузка файла в colligendis

В каталоге с файлом выполните команду colligendis load -habr -f *.csv, где *.csv — название скачанного файла. Поддерживается множественная загрузка сразу из нескольких файлов: colligendis load -habr -a — в этом режиме будут перебраны все *.csv-файлы в $PWD и по очереди загружены в БД.

По какой-то причине скачанные файлы не всегда в UTF-8, а в UTF-16LE. Если утилита ругается на кодировку (исходный файл не в UTF-8), то воспользуйтесь скриптом convert_csv.sh, расположенным в корне репозитория. Выполните его командой sh ./convert_csv.sh *.csv, указав вместо *.csv имя файла, кодировку которого нужно изменить. Файл будет перекодирован в UTF-8 с сохранением имени.

Для работы скрипта нужно, чтобы в системе была установлена утилита iconv. Также вместо скрипта можно выполнить конвертацию вручную: iconv -f utf-16le -t utf-8 "$filename" > result.csv.

Просмотр статистики и информации

Просмотреть статистику можно командой view. Введите colligendis view -h для просмотра подробностей.

Например, просмотреть все статьи в блоге можно командой colligendis view habr --articles. Вывод можно отсортировать ключом -s по дате (date) или по названию (name), например, colligendis view habr --articles -s name. В результате будет отображена таблица с перечнем статей.

Просмотр статистики

Просмотр статистики выполняется сомандой collect.

Просмотреть количество просмотров всех статей за предыдущий период можно командой:

$ colligendis collect --habr
2024/07/07 11:31:52 Total habr views: 36197

Просмотреть подробную статистику по статьям с приростом просмотров по каждой статье можно так:

colligendis collect --habr -f

В результате будет отобажена таблица с полной статистикой по статьям:

Сократить выдачу по количеству строк в таблице можно ключом -l:

colligendis collect --habr -f -l 5

В примере выше количество строк в выдаче сокращено до 5:

Выдачу можно отсортировать по количеству просмотров за неделю:

colligendis collect --habr -f -l 5 -s views

Просмотр статей и авторов

Утилита позволяет просмотреть информацию обо всех статьях, опубликованных в блоге, и авторах.

Для вывода перечня всех статей воспользуйтесь командой view:

colligendis view habr --articles

В результате будет отображена таблица со всеми статьями в блоге. Сортировка по умолчанию — по дате публикации.

Здесь так же можно задать сортировку ключом -s (поддерживаются name и date).

Генерация статистики в PDF

Для генерации в PDF используется LaTeX, он должен быть установлен в системе. Например, сгенерировать статистику по Хабру можно командой colligendis collect --habr --file. Если все пройдет успешно, в $PWD или рядом с исполняемым файлом появится PDF-файл stats.pdf с подробной статистикой по блогу.

В файле несколько разделов:

  • краткая статистика с главными цифрами;
  • «топ-5» статей, авторов и т.д.;
  • полная статистика по всем статьям и авторам.