Архив метки: документация

Документация South — Перевод. Что такое миграция?

Для непосвящённых: миграция (migrations), так же известная как 'schema evolution' или 'mutations' — это способ изменения схемы вашей БД с одной версии на другую. Django сам по себе может лишь добавлять новые модели, но почти во всех проектах часто происходят изменения самой модели — добавляются поля, изменятся свойства полей, и т.д.
South, и другие аналогичные решения, предоставляет способ обойти эту проблему, давая Вам инструмент для лёгкого и предсказуемого изменения схемы вашей БД. Вы пишете миграцию, которая говорит South как перейти с одной версии на другую, и, связывая эти миграции в цепочку, Вы можете двигаться вперёд или назад по истории изменений схемы вашей БД. 
В South, миграция это так же способ создания БД — первая миграция на самом деле миграция из пустой схемы к вашей схеме. Таким образом Вы можете как воссоздать самую последнюю версию схемы БД, так и проапгрейдить любую из устаревших, просто запустив миграцию с определённой точки. 
В процессе этого руководства мы покажем Вам как миграция работает и как она может быть полезна на разных примерах.

Автор: Ishayahu Lastov

Документация South — Перевод. Про South

South привносит миграцию в приложения на Django. Его главная цель — предоставить простой, стабильный и независящий от БД слой миграции чтобы избавить Вас от хлопот по обслуживанию изменений схемы БД в ваших приложениях.

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

Хотя South начинался как малоизвестный проект, он медленно набирал популярность и теперь стал одним из самых популярных инструментов для изменения схемы приложений Django.

Основные возможности

  • Создание автоматической миграции: South может отслеживать изменения в файле models.py file и автоматически создавать миграцию, которая отражает эти изменения.
  • Не зависит от конкретной БД: Насколько это вообще возможно South не зависит от используемой Вами БД, поддерживая 5 типов БД.
  • Подкован в приложениях: South знает что такое приложения и умеет с ними работать, позволяя Вам проводить миграцию для некоторых ваших приложений и оставляя остальные на совести syncdb.
  • VCS-proof: South оповестит Вас если кто-то ещё делает миграцию для выбранного приложения и ваши миграции вступают в конфликт.

Краткая история

Изначально South был разработан Torchbox в 2008, когда ещё не было другой системы, которая могла предоставить нам необходимый функционал. В короткие сроки код системы был открыт и она получила популярность после представления на панели Schema Evolution на DjangoCon 2008.

Где-то в 2009, она стала самой популярной системой среди всех альтернативных вариантов и, похоже, её популярность будет только расти. Хотя есть множество запросов по интеграции South или чего-то похожего напрямую в Django, такой интеграции ещё не было сделано, в основном по причине некоторой незрелости систем миграции.

Автор: Ishayahu Lastov

Выражение raise

raise_stmt ::= «raise» [expression [«from» expression]]

В случае отсутствия expression, повторно возбуждается последнее исключение, которое было активно в данной области. Если такого исключения нет, то возбуждается исключение RuntimeError, чтобы сообщить о данной ошибке.

В противном случае raise выполняет первый expression и получает объект исключения. Он должен являться либо подклассом либо экземпляром BaseException. Если первый expression является именем класса, то создается объект путём вызова класса без передачи аргументов. Читать →

Подготовка технической документации с использованием asciidoc и DocBook

Это мой конспект для выступления на семинаре, проводившемся нашей LUG. См. также презентацию к докладу.

Глава 1. Актуальность, цели и задачи

Вобще говоря, разработка технической документации — это достаточно обширная область. Техническая документация, по идее, прилагается чуть ли не ко всему подряд — инструкция к чайнику, проектная документация к мосту, мануал к программе. Конечно, в разных случаях аудитория у документов разная, разные и цели подготовки документации, а потому используются разные подходы. Я буду говорить в основном о подготовке документации к программным продуктам, хотя практически всё это применимо и к разработке других видов документации (хотя, вероятно, предлагаемой методики недостаточно).

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

  • Полная документация к большому продукту будет большой. Поэтому необходимо обеспечить автору документации простые и удобные средства для её подготовки, стараться не тратить время автора на посторонние вещи типа оформления этой документации или тонкостей xml-разметки;
  • Пользователи у продукта, возможно, будут разные, а потому документацию необходимо предоставлять в разных форматах; самые популярные форматы — PDF, HTML и CHM;
  • Так как пользователи разные, разной должна быть комплектация документации. В одних случаях нужно только руководство пользователя, в других — только руководство программиста, в третьих — и то, и другое.

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

Глава 2. Обзор технологий

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

  • MS Word и подобные системы;

  • Системы «единого источника»:

    • Help&Manual и аналоги;
    • DocBook;
    • DITA;
    • и другие.

Рассмотрим некоторые из этих технологий несколько подробнее.

Глава 3. Help&Manual

Главным плюсом этой системы часто является то, что она уже внедрена и работает. Также несомненный плюс — это система единого источника, т.е. из одного текста можно получить документ в разных форматах. Особенность этой программы и аналогов: это WISIWYG-системы. Насчёт того, является ли эта особенность плюсом или минусом, по сей день не утихают споры. Плюс WISIWYG-технологий очевиден, он заложен в названии: можно сразу видеть, как будет выглядеть текст в результате. К минусам WISIWYG относят следующие пункты:

  • Есть такое высказывание: если система предоставляет возможность что-нибудь настраивать, она, фактически, заставляет вас это настраивать. В данном случае это относится к тому, что автор тратит время не только на написание текста, но и на его оформление, хотя это, по идее, не его задача.
  • Такие системы склонны порождать совершенно дикую и нечитаемую разметку при конвертировании в HTML, LaTeX и другие подобные форматы. Например, легко можно получить разметку наподобие: разметка. Это сказывается, как только появляется необходимость поправить такую разметку «руками».
  • При работе в таких системах люди склонны использовать не логическую, а физическую разметку (например, помечать кусок текста жирным шрифтом, вместо того чтобы отмечать этот текст как заголовок). Что интересно, большинство таких систем предоставляют возможность использования логической разметки, иногда даже удобную, но по каким-то психологическим соображениям люди не склонны её использовать. Это приводит к проблемам при изменении общего стиля оформления документа, а также зачастую при конвертировании в другие форматы.

В связи с послед

Об изготовлении EPUB из DocBook

Тут не так давно я уже упоминал, что из DocBook можно делать, в том числе, и EPUB. Однако процесс не вполне тривиальный; мне кажется, его стоит расписать несколько подробнее.

Вот тут в IBM DeveloperWorks описан такой процесс. Однако изготовленный по этому рецепту файл будет обладать парой недостатков:

  • Это будет файл устаревшего формата «Open Epub»;
  • В нём не будет внедрённых шрифтов.

Такой файл благополучно открывается чем-нибудь типа Okular. Однако AdobeViewer на читалках типа PocketBook 301+ в таких файлах показывает русские буквы вопросиками. Это происходит из-за того, что встроенного шрифта в файле нет, AdobeViewer пытается использовать шрифт по умолчанию, а в нём нет русских букв. Читать →