chore: add docs

.github/workflows/docs-deploy-test.yml

@@ -0,0 +1,23 @@
+name: Test documentation deployment
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test-docs-deploy:
+    name: Test documentation deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Install tsconfig
+        run: npm i @gravity-ui/tsconfig
+      - name: Install dependencies
+        run: npm run docs:deps
+      - name: Build
+        run: npm run docs:build

.github/workflows/docs-deploy.yml

@@ -0,0 +1,38 @@
+name: Documentation Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    name: Build and Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Install docs dependencies
+        run: npm run docs:deps
+        shell: bash
+      - name: Build docs
+        run: npm run docs:build
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./dist-docs
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'

.gitignore

@@ -4,3 +4,10 @@
 node_modules
 build
 coverage
+
+# Artifacts
+dist
+dist-docs
+docs/diplodoc/pages/api
+.cache
+.tmp

docs/diplodoc/.yfm

@@ -0,0 +1,7 @@
+allowHTML: true
+staticContent: true
+addSystemMeta: true
+lang: en
+langs:
+  - en
+search: true

docs/diplodoc/index.yaml

@@ -0,0 +1,12 @@
+title: Date Utils
+base: ./
+meta:
+  title: Date Utils
+  noIndex: true
+links:
+  - title: Overview
+    href: ./pages/overview.md
+  - title: Get started
+    href: ./pages/get-started.md
+  - title: API
+    href: ./pages/api/overview.md

docs/diplodoc/pages/get-started.md

@@ -0,0 +1,182 @@
+# Getting Started
+
+## Installation
+
+You can install the Date Utils library using npm or yarn:
+
+```bash
+# Using npm
+npm install @gravity-ui/date-utils
+
+# Using yarn
+yarn add @gravity-ui/date-utils
+```
+
+## Basic Usage
+
+### Importing
+
+You can import the specific functions you need:
+
+```typescript
+import {dateTimeParse, dateTime, settings} from '@gravity-ui/date-utils';
+```
+
+### Parsing Dates
+
+The `dateTimeParse` function is the main entry point for parsing dates. It can parse dates from various formats:
+
+```typescript
+import {dateTimeParse} from '@gravity-ui/date-utils';
+
+// Parse from object
+const date1 = dateTimeParse({year: 2021, month: 7, day: 7});
+
+// Parse from array [year, month, day]
+const date2 = dateTimeParse([2021, 7, 7]);
+
+// Parse from string
+const date3 = dateTimeParse('2021-08-07');
+
+// Parse from timestamp (milliseconds)
+const date4 = dateTimeParse(1621708204063);
+
+// Parse relative dates
+const now = dateTimeParse('now');
+const yesterday = dateTimeParse('now-1d');
+const nextMonth = dateTimeParse('now+1M');
+const startOfDay = dateTimeParse('now/d');
+const startOfNextDay = dateTimeParse('now+1d/d');
+```
+
+### Creating DateTime Objects
+
+The `dateTime` function creates a DateTime object:
+
+```typescript
+import {dateTime} from '@gravity-ui/date-utils';
+
+// Current date and time
+const now = dateTime();
+
+// From a string
+const date1 = dateTime({input: '2021-08-07'});
+
+// With a specific format
+const date2 = dateTime({input: '2021-08-07', format: 'YYYY-MM-DD'});
+
+// With a specific time zone
+const date3 = dateTime({timeZone: 'Asia/Tokyo'});
+```
+
+### Formatting Dates
+
+DateTime objects have a `format` method for formatting dates:
+
+```typescript
+import {dateTime} from '@gravity-ui/date-utils';
+
+const date = dateTime({input: '2021-08-07T12:30:45'});
+
+// Basic formatting
+console.log(date.format('YYYY-MM-DD')); // '2021-08-07'
+console.log(date.format('DD/MM/YYYY')); // '07/08/2021'
+console.log(date.format('MMMM D, YYYY')); // 'August 7, 2021'
+console.log(date.format('HH:mm:ss')); // '12:30:45'
+
+// ISO string
+console.log(date.toISOString()); // '2021-08-07T12:30:45.000Z'
+```
+
+### Manipulating Dates
+
+DateTime objects provide methods for manipulating dates:
+
+```typescript
+import {dateTime} from '@gravity-ui/date-utils';
+
+const date = dateTime({input: '2021-08-07'});
+
+// Adding time
+const tomorrow = date.add(1, 'd');
+const nextWeek = date.add(1, 'w');
+const nextMonth = date.add(1, 'M');
+
+// Subtracting time
+const yesterday = date.subtract(1, 'd');
+const lastWeek = date.subtract(1, 'w');
+const lastMonth = date.subtract(1, 'M');
+
+// Start/end of time periods
+const startOfDay = date.startOf('day');
+const endOfMonth = date.endOf('month');
+```
+
+### Working with Time Zones
+
+DateTime objects provide methods for working with time zones:
+
+```typescript
+import {dateTime, getTimeZonesList, guessUserTimeZone} from '@gravity-ui/date-utils';
+
+// Get the user's time zone
+const userTimeZone = guessUserTimeZone();
+
+// Get a list of all time zones
+const timeZones = getTimeZonesList();
+
+// Create a date in a specific time zone
+const tokyoDate = dateTime({timeZone: 'Asia/Tokyo'});
+
+// Convert to a different time zone
+const newYorkDate = tokyoDate.timeZone('America/New_York');
+
+// Get the time zone offset
+console.log(tokyoDate.utcOffset()); // minutes
+```
+
+### Working with Relative Dates
+
+The library provides support for parsing relative date expressions:
+
+```typescript
+import {dateTimeParse} from '@gravity-ui/date-utils';
+
+// Current date and time
+const now = dateTimeParse('now');
+
+// 1 day ago
+const yesterday = dateTimeParse('now-1d');
+
+// 1 day ago + 1 month
+const complexDate = dateTimeParse('now-1d+1M');
+
+// Start of today
+const startOfToday = dateTimeParse('now/d');
+
+// Start of tomorrow
+const startOfTomorrow = dateTimeParse('now+1d/d');
+```
+
+### Settings and Localization
+
+The library provides settings for configuration and localization:
+
+```typescript
+import {settings} from '@gravity-ui/date-utils';
+
+// Get current locale
+const currentLocale = settings.getLocale(); // default is "en"
+
+// Load and set a new locale
+settings.loadLocale('de').then(() => {
+  settings.setLocale('de');
+});
+
+// Customize locale settings
+settings.updateLocale({weekStart: 0}); // change first day of week
+```
+
+## Next Steps
+
+For more detailed information about the library's features and API, check out the [API documentation](./api/overview.md).

docs/diplodoc/pages/overview.md

@@ -0,0 +1,21 @@
+# Overview
+
+## About Date Utils
+
+**Date Utils** is a library for dealing with dates and times in JavaScript built with [dayjs](https://day.js.org/).
+
+## Key Features
+
+- **Date and Time Parsing**: Parse dates from various formats, including ISO strings, timestamps, and custom formats
+- **Date and Time Formatting**: Format dates in various formats, including custom formats
+- **Time Zone Support**: Work with dates in different time zones
+- **Relative Time Parsing**: Parse relative time expressions like "now-1d" or "now/d"
+- **Duration Calculations**: Work with time durations
+- **Locale Support**: Support for different locales and languages
+
+## Roadmap
+
+We are actively working on library development and continuously improving its features. Here is the list of the priority major features:
+
+- ⏳ Support Unicode Technical Standard #35 format ([#29](https://github.com/gravity-ui/rfc/issues/29))
+- ⏳ Get rid of dayjs ([#23](https://github.com/gravity-ui/rfc/issues/23))

docs/diplodoc/toc.yaml

@@ -0,0 +1,27 @@
+title: ''
+href: index.yaml
+navigation:
+  logo:
+    url: '/date-utils'
+    dark:
+      icon: https://storage.yandexcloud.net/gravity-ui-assets/gravity-logo-dark.svg
+      text: Date Utils
+    light:
+      icon: https://storage.yandexcloud.net/gravity-ui-assets/gravity-logo-light.svg
+      text: Date Utils
+  header:
+    leftItems:
+      - text: Github ➚
+        type: link
+        url: https://github.com/gravity-ui/date-utils
+    rightItems:
+      - type: search
+      - type: controls
+items:
+  - name: Overview
+    href: ./pages/overview.md
+  - name: Get started
+    href: ./pages/get-started.md
+  - name: API
+    href: ./pages/api
+    autodoc: true

docs/docs-gen.json

@@ -0,0 +1,4 @@
+{
+  "pathToTocFile": "./diplodoc/toc.yaml",
+  "pathToDocsFolder": "./diplodoc"
+}

docs/gulpfile.docs.js

@@ -0,0 +1,34 @@
+const {exec} = require('node:child_process');
+const path = require('node:path');
+
+const browserSync = require('browser-sync').create();
+const {watch, series, parallel} = require('gulp');
+
+const DIST_PATH = '../dist-docs';
+
+function build(cb) {
+    exec('npm run docs:build', (err, stdout, stderr) => {
+        process.stdout.write(stdout);
+        process.stdout.write(stderr);
+        cb(err);
+    });
+}
+
+function serve(cb) {
+    browserSync.init({server: path.resolve(DIST_PATH), port: 7007});
+    cb();
+}
+
+function reload(cb) {
+    browserSync.reload();
+    cb();
+}
+
+function watchFiles() {
+    const watcher = watch(['./diplodoc/**/*', './src/**/*', '../src/**/*']);
+    watcher.on('change', function () {
+        series(build, reload)();
+    });
+}
+
+exports.default = series(build, parallel(serve, watchFiles));