Важно

Перевод - это работа сообщества : ссылка:Вы можете присоединиться. Эта страница в настоящее время переводится |прогресс перевода|.

19. Приложение: Вклад в данное руководство

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

19.1. Загрузка ресурсов

Исходный текст этого документа доступен на GitHub. Обратитесь к GitHub.com за инструкциями по использованию системы контроля версий git.

19.2. Формат руководства

Это руководство написано с помощью Sphinx, генератора документов на языке Python, использующего язык разметки reStructuredText. Инструкции по использованию этих инструментов можно найти на соответствующих сайтах.

19.3. Добавление модуля

Чтобы добавить новый модуль:

  1. Сначала создайте новый каталог (непосредственно под верхним уровнем каталога qgis-training-manual) с именем нового модуля.

  2. В этом новом каталоге создайте файл под названием index.rst. Пока оставьте этот файл пустым.

  3. Откройте файл index.rst в каталоге верхнего уровня. Его первые строки:

    .. toctree::
   :maxdepth: 2

   foreword/index
   introduction/index

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

  1. Добавьте имя вашего нового модуля (т.е. имя, которое вы дали новому каталогу), а затем /index в этот список, везде, где вы хотите, чтобы ваш модуль появился.

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

  3. Откройте собственный индексный файл вашего нового модуля (имя_модуля/index.rst).

  4. В верхней части страницы создайте заголовок модуля:

    1. написать первую строку из звездочек (*).

    2. За ней следует строка, содержащая фразу разметки Модуль:, за которой следует имя вашего модуля.

    3. Завершите его еще одной строкой с таким же количеством звездочек.

    Примечание

    Подчеркивание и надчеркивание не должны быть короче строки, содержащей название модуля.

  5. Оставьте под ним свободную строку.

  6. Напишите короткий абзац, объясняющий цель и содержание модуля.

  7. Оставьте одну строку открытой, затем добавьте следующий текст:

    .. toctree::
   :maxdepth: 2

   lesson1
   lesson2

    … где урок1, урок2 и т.д. - это названия запланированных уроков.

Индексный файл на уровне модуля будет выглядеть следующим образом:

*******************************************************************************
Module: Module Name
*******************************************************************************

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2

   lesson1
   lesson2

19.4. Добавление урока

Чтобы добавить урок в новый или существующий модуль:

  1. Откройте каталог модулей.

  2. Откройте файл index.rst (созданный выше в случае новых модулей).

  3. Убедитесь, что имя запланированного урока указано под директивой toctree, как показано выше.

  4. Создайте новый файл в каталоге модуля.

  5. Назовите этот файл точно так же, как и имя, указанное в файле модуля index.rst, и добавьте расширение .rst.

Примечание

Для целей редактирования файл .rst работает точно так же, как обычный текстовый файл (.txt).

  1. Чтобы начать писать урок, напишите фразу разметки Урок, за которой следует название урока.

  2. В следующей строке напишите строку из знаков равенства (=), не короче названия урока.

  3. После этого оставьте линию открытой.

  4. Напишите краткое описание цели урока.

  5. Включите общее введение в тему. Примеры смотрите в существующих уроках в этом руководстве.

  6. Под ним начните новый абзац, начинающийся с этой фразы:

    **The goal for this lesson:**

  7. Кратко объясните предполагаемый результат прохождения этого урока.

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

Каждый урок будет разделен на несколько разделов, которые будут рассмотрены далее.

19.5. Добавление раздела

Есть два типа разделов: «Следуй за мной» и «Попробуй сам».

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

  • Раздел «Попробуй сам» дает читателю короткое задание, которое он должен выполнить самостоятельно. Обычно он сопровождается записью в поле для ответов, которая показывает или объясняет, как выполнить задание, и, по возможности, показывает ожидаемый результат.

Каждый раздел имеет свой уровень сложности. Легкий раздел обозначается ★☆☆, умеренный - ★★☆, а продвинутый - ★★★

19.5.1. Добавление раздела «Следуйте за мной»

  1. Чтобы начать этот раздел, напишите фразу разметки предполагаемого уровня сложности (как показано выше).

  2. Оставьте пробел, а затем напишите Следовать за ним:.

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

  4. В следующей строке напишите строку минусов/тире (-), не короче названия раздела.

  5. Напишите краткое вступление к разделу, объяснив его цель. Затем дайте подробные (клик за кликом) инструкции по процедуре, которую нужно продемонстрировать.

  6. В каждый раздел включите внутренние ссылки, внешние ссылки и скриншоты, если это необходимо.

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

19.5.2. Добавление раздела «Попробуй сам»

  1. Чтобы начать этот раздел, напишите фразу разметки предполагаемого уровня сложности (как показано выше).

  2. Оставьте пробел, а затем напишите Попробуйте себя:.

  3. В следующей строке напишите строку минусов/тире (-), не короче названия раздела.

  4. Объясните упражнение, которое вы хотите, чтобы читатель выполнил. При необходимости обратитесь к предыдущим разделам, урокам или модулям.

  5. Приложите скриншоты, чтобы пояснить требования, если простое текстовое описание непонятно.

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

  1. Сначала создайте пользовательский сворачиваемый виджет, содержащий ответ:

    .. admonition:: Answer
   :class: dropdown

  2. Сохраняя отступ относительно вышеуказанного блока, напишите инструкции по выполнению задания, используя ссылки и изображения, где это необходимо.

19.6. Добавить заключение

Завершить урок:

  1. Напишите фразу В заключение, а затем новую строку минусов/черточек (-).

  2. Напишите вывод к уроку, объяснив, какие понятия были рассмотрены на уроке.

19.7. Добавить раздел для дальнейшего чтения

Этот раздел является необязательным.

  • Напишите фразу Дальнейшее чтение, за которой следует новая строка минусов/черточек (-).

  • Включите ссылки на соответствующие внешние сайты.

19.8. Добавьте раздел «Что дальше?

  1. Напишите фразу Что дальше?„“, а затем новую строку минусов/тире (-``).

  2. Объясните, как этот урок подготовил учеников к следующему уроку или модулю.

  3. Не забудьте при необходимости изменить раздел «Что дальше» предыдущего урока, чтобы он ссылался на ваш новый урок. Это необходимо, если вы вставили новый урок среди существующих уроков или после существующего урока.

19.9. Использовать разметку

Чтобы придерживаться стандартов этого документа, вам нужно будет добавить в текст стандартную разметку.

19.9.1. Новые концепции

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

This sample text shows how to introduce a *new concept*.

19.9.2. Акцент

  • Чтобы подчеркнуть важный термин, который не является новым понятием, выделите его жирным шрифтом, заключив в двойные звездочки (**).

  • Используйте его осторожно! Если использовать его слишком часто, читателю может показаться, что вы кричите или относитесь к нему снисходительно.

This sample text shows how to use **emphasis** in a sentence. Include the
punctuation mark if it is followed by a **comma,** or at the **end of the
sentence.**

19.9.3. Images

  • При добавлении изображения сохраните его в папке img рядом с файлом урока.

  • Включите его в документ следующим образом:

    .. figure:: img/image_file.extension
   :align: center

  • Не забудьте оставить открытую строку над и под разметкой изображения.

19.9.6. Использование моноширинного текста

  • Когда вы пишете текст, который должен ввести пользователь, имя пути или имя элемента базы данных, например, имя таблицы или столбца, вы должны писать его с ``моноширинным интервалом““. Например:

    Enter the following path in the text box: ``path/to/file``.

19.9.7. Маркировка элементов графического интерфейса

  • Если вы ссылаетесь на элемент графического интерфейса, например, кнопку, вы должны написать ее имя в формате этикетки графического интерфейса. Например:

    To access this tool, click on the :guilabel:`Tool Name` button.

  • Это также относится к случаям, когда вы упоминаете название инструмента, не требуя от пользователя нажатия кнопки.

19.9.9. Добавить заметки

  • Возможно, вам понадобится добавить в текст примечание, которое объясняет дополнительные детали, которые не так просто сделать частью потока урока. Вот такая разметка:

    [Normal paragraph.]

.. note:: Note text.
  New line within note.

  New paragraph within note.

[Unindented text resumes normal paragraph.]

19.9.10. Добавление примечания о спонсорстве/авторстве

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

Если вы вызвались написать модуль, урок или раздел в своем собственном качестве, а не от имени спонсора, вы можете включить примечание об авторстве под заголовком модуля, урока или раздела, автором которого вы являетесь. Она должна иметь вид Этот [модуль/урок/раздел] подготовлен [имя автора]. Не добавляйте дополнительный текст, контактную информацию и т.д. Такая информация должна быть добавлена в раздел «Соавторы» в предисловии, вместе с названием (названиями) добавленной вами части (частей). Если вы внесли только улучшения, исправления и/или дополнения, укажите себя в качестве редактора.

19.10. Спасибо!

Благодарим вас за вклад в этот проект! Тем самым вы делаете QGIS более доступным для пользователей и повышаете ценность проекта QGIS в целом.