Внесение документации

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

Вклад в документацию заслуживает самого большого уважения со стороны разработчиков ядра и сообщества django CMS.

Документация должна быть:

  • записанный с использованием правильного синтаксиса Sphinx/restructuredText (см. ниже); расширение файла должно быть .rst

  • 100 символов в строке

  • написанные на английском языке с использованием британской английской орфографии и пунктуации

  • доступным - вы должны предполагать, что читатель в меру знаком с Python и Django, но не с чем-то еще. Ссылайтесь на документацию библиотек, которые вы используете, например, даже если они «очевидны» для вас

Слияние документации происходит довольно быстро и безболезненно.

За исключением мельчайших изменений, мы рекомендуем вам проверить их перед отправкой.

Создание документации

Выполните те же шаги, что и выше, чтобы форкнуть и клонировать проект локально. Далее, cd в django-cms/docs и установите требования:

make install

Теперь вы можете протестировать и запустить документацию локально, используя:

make run

Это позволит вам просмотреть изменения в локальном браузере, используя http://localhost:8001/.

Примечание

Что это дает

make install примерно эквивалентно:

virtualenv env
source env/bin/activate
pip install -r requirements.txt
cd docs
make html

make run запускает make html, и обслуживает собранную документацию на порту 8001 (то есть по адресу http://localhost:8001/).

Затем он следит за каталогом docs; когда он обнаружит изменения, он автоматически перестроит документацию и обновит страницу в вашем браузере.

Правописание

Мы используем sphinxcontrib-spelling, который в свою очередь использует pyenchant и enchant для проверки орфографии документации.

Перед подачей документации необходимо проверить орфографию.

Важно

Мы используем британский английский, а не американский английский. Это означает, что мы используем colour, а не color, emphasise, а не emphasize и так далее.

Установите программное обеспечение для правописания

sphinxcontrib-spelling и pyenchant - это пакеты Python, которые будут установлены в virtualenv docs/env, когда вы запустите make install (см. выше).

Вам также потребуется установить enchant, если он еще не установлен. Простой способ проверки - запустить make spelling из каталога docs. Если он запустится успешно, вам ничего не нужно делать, но если нет, вам придется установить enchant для вашей системы. Например, на OS X:

brew install enchant

или Debian Linux:

apt-get install enchant

Проверьте орфографию

Беги:

make spelling

в каталоге docs для проведения проверок.

Примечание

Этот скрипт ожидает найти virtualenv по адресу docs/env, как установлено make install (см. выше).

Если орфографических ошибок не обнаружено, make spelling сообщит:

build succeeded.

Иначе:

build finished with problems.
make: *** [spelling] Error 1

В нем будут перечислены все ошибки в вашей оболочке. Неправильно написанные слова также будут перечислены в build/spelling/output.txt.

Слова, которых нет во встроенном словаре, можно добавить в docs/spelling_wordlist. Если вы уверены, что слово неправильно помечено как ошибочно написанное, добавьте его в документ ``spelling_wordlist`` в алфавитном порядке. **Пожалуйста, не добавляйте новые слова, если вы не уверены, что они должны быть там.

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

Важно

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

Создание запроса на исправление

Перед фиксацией изменений необходимо проверить орфографию с помощью make spelling и перестроить документацию с помощью make html. Если все выглядит хорошо, то самое время отправить изменения на GitHub и открыть запрос на исправление (pull request) обычным способом.

Структура документации

Наша документация разделена на следующие основные разделы:

Разметка документации

Разделы

Мы в основном следуем соглашениям документации Python для обозначения разделов:

##########
Page title
##########

*******
heading
*******

sub-heading
===========

sub-sub-heading
---------------

sub-sub-sub-heading
^^^^^^^^^^^^^^^^^^^

sub-sub-sub-sub-heading
"""""""""""""""""""""""

Встроенная разметка

  • используйте обратные знаки - `` - для:

    • литералы:

      The ``cms.models.pagemodel`` contains several important methods.

    • имена файлов:

      Before you start, edit ``settings.py``.

    • названия полей и других специфических элементов в интерфейсе администратора:

      Edit the ``Redirect`` field.
  • используйте подчеркивание - *Home* - вокруг:

    • названия доступных опций в или части Admin:

      To hide and show the *Toolbar*, use the...

    • названия важных режимов или государств:

      ... in order to switch to *Edit mode*.

    • значения в или из полей:

      Enter *Home* in the field.
  • используйте сильное ударение - ** - вокруг:

    • кнопки, выполняющие действие:

      Hit **View published** or **Save as draft**.

Правила использования технических слов

Должен быть один последовательный способ передачи любого технического слова в зависимости от его контекста. Пожалуйста, следуйте этим правилам:

  • в общем случае просто используйте это слово, как любое обычное слово, без капитализации или выделения: «Теперь можно использовать вашу вставку».

  • в начале предложений или заголовков, пишите с заглавной буквы обычным способом: «Руководство по управлению размещением»

  • при введении термина в первый раз или впервые в документе, вы можете выделить его, чтобы привлечь к нему внимание: «Разделители - это специальные поля модели».

  • когда слово относится конкретно к объекту в коде, выделите его как литерал: «Placeholder методы могут быть перезаписаны по мере необходимости» - когда уместно, связывайте термин с дополнительной справочной документацией, а также просто выделяйте его.

Ссылки

Создать:

.. _testing:

и использовать:

:ref:`testing`

внутренние перекрестные ссылки в свободном доступе.

Используйте абсолютные ссылки на другие страницы документации - :doc:`/how_to/toolbar` - вместо относительных ссылок - :doc:`/../toolbar`. Это облегчает поиск и замену при перемещении элементов в структуре.

Внесение кода
Содействие в переводе
Вернуться на верх