Документирование ваших проектов с помощью Daux.io

() translation by (you can also view the original English article)

Final product image — What You'll Be Creating

Документирование проекта может быть неприятным, но этого не должно быть. Существует множество инструментов для выполнения этой работы - я часто использую Daux.io из-за его гибкости.

В этой статье я покажу вам, почему вы должны документировать, как вы можете получить Daux.io и как вы можете начать использовать его прямо сейчас, чтобы сделать ваши проекты намного лучше.

Зачем нужна документация

Написание документации для вашего проекта может быть самым важным решением, которое вы принимаете. Причина, по которой это часто игнорируется для веб-проектов, заключается в том, что на карту не так много поставлено.

Возьмите Boeing 787, например. Этот продукт имеет обширную документацию, поддерживающую все аспекты от проектирования до обслуживания. Есть даже около 150 страниц руководства, документирующих 787 характеристик, которые необходимо учитывать при планировании аэропортов.

Почему самолет должен иметь развернутую документацию, пока нет веб-сайта?

Я считаю, что есть три основные причины:

Гораздо больше денег
Соображения безопасности
Вопросы масштаба

На сайтах редко заботятся об безопасности, но как только масштаб или деньги наберут обороты, вы можете быть уверены, что появится документация. Все крупные проекты, такие как Twitter и Facebook, имеют ошеломительное количество информации, доступной как для разработчиков, так и для третьих лиц.

Веб-сайты, которые генерируют много дохода, часто также предпочитают создавать хорошую документацию. Идея состоит в том, что если что-то нужно изменить, каждый может ссылаться на документацию, и на веб-сайте гораздо меньше шансов потерять деньги из-за ущерба продолжительности работы.

Означает ли это, что вы можете обойтись без документации для небольшого проекта? Конечно, вопрос в том, должны ли вы?

Преимущества документации

Документация обеспечивает общую систему координат для проекта. Преимущество этого довольно очевидно при работе в команде, но его упускают из виду, когда кто-то работает в одиночку.

Если вы создадите свои веб-сайты для создания жилья, вы можете построить хотя бы несколько раз в год. Вы помните, как веб-сайт, который вы создали в январе, автоматически обновляет его содержимое, когда вы приходите посмотреть его в следующем августе? Что, если компания попросит вас передать проект другому разработчику? Вы можете тратить час каждое утро, отвечая на вопросы о своем коде на следующий месяц.

Даже самый последовательный кодер является непоследовательным. По мере роста и обучения мы склонны менять способ работы. Возможно, вы внесли в свой рабочий процесс инструмент сборки, например Gulp, возможно, вы начали использовать объектно-ориентированный PHP.

Документация также может объяснять ситуации, которые не очевидны в самом коде. Возможно, вы выбрали подпаритетное решение специально, просто потому, что вас попросили сделать что-то быстро, и цель оправдала средства. Это может быть добавлено в документацию, возможно, в качестве задачи для обновления позже.

Документация с Daux.io

Daux.io может сначала напугать некоторых людей, потому что это не простой HTML, его можно просмотреть только с помощью сервера. Однако установка всего этого довольно проста, и как только вы обойдете это препятствие, использование будет легким и гибким.

Получение Daux.io

Самый простой способ получить Daux.io - загрузить его из Github. Вы можете загрузить пакет, используя кнопку Загрузить ZIP на правой боковой панели. Если вы опытный пользователь Github, вы можете клонировать его, или вы можете даже взять его из Packagist через композитор.

Если вы загружаетесь из Github, вы должны получить папку с именем daux.io-master.

Переименуйте его в "документацию" и переместите на свой рабочий стол для большей ясности. Чтобы написать вашу документацию, вам на самом деле ничего не нужно. Вы можете редактировать файлы Markdown в любом редакторе и использовать команду, чтобы преобразовать все это в HTML для удобства обмена. Тем не менее, лучше всего просмотреть нашу работу по мере продвижения, поэтому мы сделаем для этого некоторую подготовку.

Предварительный просмотр документации

Чтобы просмотреть документы, нам понадобится сервер. К счастью, все предусмотрено в папке проекта Daux.io, нам просто нужны предварительные условия для запуска сервера: npm и Grunt.

Установка npm и Grunt

Самый простой способ взять npm (Node Package Manager) - установить Node. Перейдите на сайт Node и загрузите программу установки. После установки у вас появится возможность использовать команду npm в терминале (в Linux/OS X) или в командной строке (Windows).

Маленькое замечание: я буду ссылаться на командную строку на Windows и терминал на Linux/OS X с тем же словом: terminal.

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

1	npm install -g grunt-cli

Теперь у вас есть базовые инструменты, необходимые для начала работы. Если вы новичок в npm, я настоятельно рекомендую узнать больше об этом. Это позволяет легко устанавливать инструменты, и вам необязательно знать, что Node.js использует инструменты для работы с npm (например, Grunt).

Все описанное до этого момента необходимо только в том случае, если у вас еще нет установленных инструментов. Независимо от того, сколько экземпляров документации Daux.io у вас есть, вам больше не придется это делать.

Совет: узнайте больше о инструментах командной строки, следуя серии для начинающих Командная строка для веб-дизайна Кезза Брейси.

Пользователи Windows: установка PHP

Этот шаг предназначен только для пользователей Windows, OS X и большинство дистрибутивов Linux поставляются с предустановленной PHP, поэтому, если вы находитесь на этих платформах, вы можете пропустить этот раздел. К сожалению, установка командной строки PHP в Windows - это немного хлопот, вот и все.

Перейдите на страницу загрузки PHP и возьмите версию PHP, которую вы хотели бы. При тестировании я использовал версию "VC11 x86 Non Thread Safe". Я загрузил и извлек этот архив в свою корневую папку, C:/ и переименовал результирующую папку в "php". В конце процесса у вас должна быть папка с именем "php" в вашем основном каталоге C:/, где папка должна содержать "php.exe" .

Затем нам нужно убедиться, что команда PHP может быть запущена из любого места. В Windows 7 простейший способ сделать это - перейти в меню Пуск, щелкнуть правой кнопкой мыши Компьютер и выбрать Свойства. Нажмите Дополнительные параметры системы на левой боковой панели. Перейдите на вкладку Дополнительно, затем нажмите кнопку Переменные среды внизу.

Вам нужно будет щелкнуть по пути на верхней панели, а затем отредактировать. В самом конце значения добавьте ссылку на папку, что-то вроде этого: "C:\Users\Dani\environment". Это должна быть папка в вашей собственной папке пользователя. После этого сохраните все и создайте эту папку. (Если вы используете другую версию Windows, взгляните на Computerhope, она перечисляет, как это сделать в нескольких версиях).

Внутри этой папки создайте файл с именем "phppath.cmd". Отредактируйте этот файл с помощью любого текстового редактора и добавьте следующий контент:

1	PATH=%PATH%;C:\Users\Dani\environment
2	php -v

После этого перейдите в эту папку через командную строку, набрав cd% userprofile%/environment и запустите следующую команду: phppath.

Наконец, закройте командную строку и заново откройте ее, теперь php будет доступен глобально. Опять же, это то, что вам нужно сделать только один раз и только в Windows.

Настройка Daux.io

Еще в вашем терминале перейдите к папке проекта. Помните, что на этом этапе это должно быть на рабочем столе. В Windows вы можете использовать следующую команду для перехода к папке проекта:

1	cd %userprofile%/Desktop/documentation

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

1	cd ~/Desktop/documentation

Первая команда, которую вы должны указать, - npm install. Как только это закончится, запустите npm update, чтобы убедиться, что все обновлено. Эти команды устанавливают и обновляют вне зависимости от Daux.io. Вам нужно будет сделать это для каждого экземпляра Daux.io, который у вас есть.

Запуск предварительного просмотра

Мы, наконец, готовы просмотреть нашу документацию. Теперь это вопрос одной команды, все, что вам нужно сделать, это ввести grunt в терминал (убедитесь, что вы находитесь в папке документации при выдаче команды).

Через несколько секунд вы должны увидеть что-то вроде этого:

Это означает, что сервер запущен и работает, новая вкладка, возможно, уже открылась в вашем браузере. Если это не так, посмотрите на IP, показанный рядом с "Прослушивание" на терминале, и введите его в свой браузер. В моем примере этот IP-адрес "127.0.0.1:8085".

Примечание: в некоторых случаях вкладка открывается, но отображается "страница не найдена" или какая-либо аналогичная ошибка. В этом случае перезагрузите вкладку через пару секунд, серверу потребуется немного больше времени для инициализации.

Теперь вы должны увидеть документацию по умолчанию, представленную в браузере. Представление, которое вы видите, создается ad-hoc из файлов документации Markdown. Теперь, когда мы можем видеть, что мы делаем, давайте посмотрим на документацию.

Письменная документация

В папке "документация" вы увидите папку "docs". Она содержит вашу фактическую документацию, все остальное для Daux.io - сделать свою магию. Daux.io использует определенное соглашение об именах, чтобы дать вам полный контроль над порядком страниц.

Каждый элемент этой страницы должен начинаться с числа и подчеркивания. Чем выше число, тем ниже будет страница в документации. Если вам нужна одна страница, создайте файл Markdown (например: 04_Updating_Plugins), если вам нужна иерархическая структура страниц, создайте папку (например: 05_Code_Styling).

Текст после номера определяет имя страницы в документации. Моими предыдущими примерами станут "Обновление плагинов" и "Стилирование кода". Обязательно используйте только альфа-символы и символы подчеркивания, символы подчеркивания будут преобразованы в пробелы.

Отсюда, когда вы плаваете в плавании, все, что вам нужно сделать, это отредактировать ваши файлы в стиле Markdown. Если вы не знакомы с уценкой, взгляните на Cheatsheet Markdown. Это по существу способ разметки текста (указать заголовки, ссылки, изображения и т. д.) без HTML-кода.

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

Целевые страницы

Еще одна замечательная вещь, которую Daux.io позволяет вам сделать, - это создать целевую страницу для ваших разделов. Вся ваша документация может получить целевую страницу, если вы создаете файл "_index.md" . Взгляните на пример по умолчанию, чтобы получить представление о форматировании.

Каждая секция также может иметь целевую страницу. Если в разделе нет целевой страницы, элемент меню верхнего уровня нигде не нажимается, он просто открывает список подсекций. Если вы хотите, чтобы запись верхнего уровня имела свою собственную страницу, создайте файл "index.md" в папке для раздела.

Управление несколькими документами

Для некоторых проектов может потребоваться несколько документов. Веб-сайт может гарантировать документацию конечного пользователя и документацию разработчика, которая будет содержать совершенно другую информацию.

Один из способов управления несколькими требованиями к документации, например, заключается в создании нескольких экземпляров Daux.io. Однако это требует, чтобы вы запускали сервер отдельно и снова устанавливали некоторые компоненты. К счастью, есть лучший способ!

Взгляните на файл "global.json" в основной папке документации. Если вы откроете его в текстовом редакторе, вы увидите, что для параметра docs_directory установлено значение docs. Создайте копию каталога документов, назовите его "user_docs" и добавьте в него несколько разных фиктивных файлов, чтобы можно было отличить его от исходной документации.

Теперь измените параметр docs_directory на user_docs и перезагрузите документацию в вашем браузере. Теперь вы просматриваете содержимое новой папки. Это позволяет легко переключаться между документами на лету без необходимости перезагрузки сервера или использования другого экземпляра Daux.io.

Создание окончательной документации

Конечно, в конце концов нам нужно распространить нашу документацию. Это лучше всего сделать в HTML-форме, и Daux.io нас охватит! В терминале, в главном каталоге вашей документации выполните следующую команду:

1	php generate.php

Это создаст "статическую" папку со всеми файлами HTML и ресурсами, необходимыми для просмотра документации. Вы можете закрепить эту папку и отправить ее кому-то или загрузить ее на сервер и связать с ней.

Расширенная настройка проекта

С помощью файла default.json можно управлять несколькими путями . По умолчанию на боковой панели будет ссылка Made by Todaymade, а также некоторые ссылки Twitter, которые вам либо не нужны, либо вы хотите настроить в своем проекте. На главной странице Daux.io перечислены параметры, которые вы можете использовать в разделе "Конфигурация" далее по странице или просто обратитесь к файлу "default.json" .

Вы можете использовать "twitter": ["yourtwittername"], чтобы добавить вашу собственную ссылку в Twitter. Ссылки можно контролировать с помощью параметра links, вот как добавить пару:

"links": {
    "GitHub Repo": "https://github.com/yourgithubrepo",
    "Support": "http://support.myproduct.com",
    "Made by Me": "http://mywebsite.com"
}

Вы можете найти все параметры на главной странице Daux.io. Вот пример полного файла default.json для воображаемого проекта.

{
    "title": "My Project",
    "tagline": "My Stylish Documentation",
    "docs_directory": "docs",
    "valid_markdown_extensions": ["md", "markdown"],
    "repo": "danielpataki/exampleproject",
    "twitter": ["danielpataki"],
    "theme": "daux-blue",
    "breadcrumbs": false,
    "template": "default",
    "clean_urls": false,
    "toggle_code": false,
    "date_modified": false,
    "float": false,
    "links": {
        "GitHub Repo": "https://github.com/danielpataki/exampleproject",
        "Support": "http://support.exampleproject.com",
        "Made by Daniel": "http://danielpataki.com"
    }
}

Заключение

Сначала настройка Daux.io может показаться сложной задачей, но это не так уж и много, особенно в системах Mac/Linux, где большинство из того, что нам нужно, предварительно установлено. Если вы не привыкли к терминалу и локальным серверам, может потребоваться некоторое время, чтобы привыкнуть к среде, но это будет окупаться в десять раз.

Как только вы начнете работать с Daux.io, вы обнаружите, что он прост в использовании, гибкий и простой в обслуживании. Ваш проект, ваш клиент, ваши сотрудники и конечные пользователи вашего проекта будут благодарны вам за ваши усилия, и, надеюсь, ваше время, потраченное на поддержку проекта, будет сведено к минимуму.