diff --git a/build.js b/build.js index af5d7e5..a4f34c0 100644 --- a/build.js +++ b/build.js @@ -2,25 +2,53 @@ const puppeteer = require('puppeteer'); const fs = require('fs'); const mdHtml = new (require('showdown').Converter)(); -const content = getParts({ - path: './src/ru/clean-copy/', - l10n: { - chapter: 'Глава' +const l10n = { + en: { + title: 'Sergey Konstantinov. The API', + author: 'Sergey Konstantinov', + chapter: 'Chapter' }, - pageBreak:'
' -}).join(''); + ru: { + title: 'Сергей Константинов. API', + author: 'Сергей Константинов', + chapter: 'Глава' + } +}; -const html = ` - - Сергей Константинов. API - - - - -
${content}
-`; +buildDocs(l10n).then(() => { + process.exit(0); +}, (e) => { + console.error(e); + process.exit(255); +}); -fs.writeFileSync('./docs/API.ru.html', html); +function buildDocs (l10n) { + return Promise.all( + Object.entries(l10n).map(([lang, l10n]) => buildDoc(lang, l10n)) + ); +} + +function buildDoc (lang, l10n) { + const content = getParts({ + path: `./src/${lang}/clean-copy/`, + l10n, + pageBreak:'
' + }).join(''); + + const html = ` + + ${l10n.title} + + + + +
${content}
+ `; + + fs.writeFileSync(`./docs/API.${lang}.html`, html); + + return buildPdf(`./docs/API.${lang}.pdf`, html); +} function getParts ({ path, l10n: { chapter }, pageBreak}) { const parts = [ @@ -52,7 +80,7 @@ function getParts ({ path, l10n: { chapter }, pageBreak}) { return parts; } -async function buildPdf() { +async function buildPdf (path, html) { const browser = await puppeteer.launch({ headless: true }); const page = await browser.newPage(); @@ -60,17 +88,10 @@ async function buildPdf() { waitUntil: 'load' }); const pdf = await page.pdf({ - path: './docs/API.ru.pdf', + path, preferCSSPageSize: true, printBackground: true }); await browser.close(); -} - -buildPdf().then(() => { - process.exit(0); -}, (e) => { - console.error(e); - process.exit(255); -}) \ No newline at end of file +} \ No newline at end of file diff --git a/docs/API.en.html b/docs/API.en.html new file mode 100644 index 0000000..185620b --- /dev/null +++ b/docs/API.en.html @@ -0,0 +1,107 @@ + + + Sergey Konstantinov. The API + + + + +

Sergey Konstantinov
The API

+ +

This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

+

Introduction

Chapter 1. On the Structure of This Book

+

The book you're holding in your hands comprises this Introduction and three large sections.

+

In Section I we are to talk about deisgning the API as a concept: how to build the architecture properly, from a high-level planning down to final interfaces.

+

Section II is dedicated to API's lifecycle: how interfaces evolve over time, and how to elaborate the product to match users' needs.

+

Finally, Section III is more about un-engineering sides of the API, like supporting, marketing and working with a community.

+

First two sections are much of of interest to engineers, when third section being more relevant to both engineers and product managers. But we insist that this section is the most important for the API software developer. Since API is the product for engineers, you cannot simply pronounce non-engineering team responsible for its product planning and support. Nobody but you understands more what product features your API is capable of.

+

Let's start.

API Design

+ \ No newline at end of file diff --git a/docs/API.en.pdf b/docs/API.en.pdf new file mode 100644 index 0000000..09202f2 Binary files /dev/null and b/docs/API.en.pdf differ diff --git a/docs/API.ru.html b/docs/API.ru.html index c5028bd..9451bab 100644 --- a/docs/API.ru.html +++ b/docs/API.ru.html @@ -1,9 +1,9 @@ - - Сергей Константинов. API - - - - -

Сергей Константинов
API

+ +

Сергей Константинов
API

Это произведение доступно по лицензии Creative Commons «Attribution-NonCommercial» («Атрибуция — Некоммерческое использование») 4.0 Всемирная.

Введение

Глава 1. О структуре этой книги

@@ -1155,4 +1155,4 @@ GET /v1/record-views/{id}?cursor={cursor}

Важно: различайте локализацию для конечного пользователя и локализацию для разработчика. В примере из п. 12 сообщение localized_message адресовано пользователю — его должно показать приложение, если в коде обработка такой ошибки невозможно. Это сообщение должно быть написано на указанном в запросе языке и отформатировано согласно правилам локации пользователя. А вот сообщение details.checks_failed[].message написано не для пользователя, а для разработчика, который будет разбираться с проблемой. Соответственно, написано и отформатировано оно должно быть понятно для разработчика — что, скорее всего, означает «на английском языке», т.к. английский де факто является стандартом в мире разработки программного обеспечения.

Следует отметить, что индикация, какие сообщения следует показать пользователю, а какие написаны для разработчика, должна, разумеется, быть явной конвенцией вашего API. В примере для этого используется префикс localized_.

И ещё одна вещь: все строки должны быть в кодировке UTF-8 и никакой другой.

- \ No newline at end of file + \ No newline at end of file diff --git a/docs/API.ru.pdf b/docs/API.ru.pdf index a768aaa..3bd63bd 100644 Binary files a/docs/API.ru.pdf and b/docs/API.ru.pdf differ diff --git a/src/en/clean-copy/01-Introduction/01.md b/src/en/clean-copy/01-Introduction/01.md new file mode 100644 index 0000000..99cce12 --- /dev/null +++ b/src/en/clean-copy/01-Introduction/01.md @@ -0,0 +1,13 @@ +### On the Structure of This Book + +The book you're holding in your hands comprises this Introduction and three large sections. + +In Section I we are to talk about deisgning the API as a concept: how to build the architecture properly, from a high-level planning down to final interfaces. + +Section II is dedicated to API's lifecycle: how interfaces evolve over time, and how to elaborate the product to match users' needs. + +Finally, Section III is more about un-engineering sides of the API, like supporting, marketing and working with a community. + +First two sections are much of of interest to engineers, when third section being more relevant to both engineers and product managers. But we insist that this section is the most important for the API software developer. Since API is the product for engineers, you cannot simply pronounce non-engineering team responsible for its product planning and support. Nobody but you understands more what product features your API is capable of. + +Let's start. \ No newline at end of file diff --git a/src/en/clean-copy/intro.html b/src/en/clean-copy/intro.html new file mode 100644 index 0000000..cbcdf4c --- /dev/null +++ b/src/en/clean-copy/intro.html @@ -0,0 +1,3 @@ +

Sergey Konstantinov
The API

+ +

This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.