Курс по продукту ALD Pro

Курс посвящен вопросам администрирования рабочих мест под управлением ОС Astra Linux в домене ALD Pro. Материал написан специально для Windows-администраторов, кому нужно сделать быстрый переход на новый стек технологий, поэтому многие вопросы объясняются в сравнении с тем, как это реализовано в Windows. В первой части курса рассматриваются вопросы администрирования Linux, когда система используется автономно, а во второй части рассматриваются особенности работы системы в составе домена ALD Pro (FreeIPA).

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

Как вносить правки

Исходные тексты курса доступны в репозитории gitflic и сверстаны в формате reStructuredText. В работе с материалами мы придерживаемся концепции Docs as Code, когда техническая документация создается с применением тех же инструментов, которые используются при разработке программного кода:

• Тексты пишутся в простом редакторе с использованием языков разметки (Markdown или reStructuredText).

• Файлы хранятся в системе контроля версий на gitflic.ru, а задачи на изменение документов ставятся через встроенную систему контроля ошибок.

• Документы компилируются в целевой формат (HTLM, PDF и др.) при помощи генератора документации Sphinx, как компьютерная программа. С момента появления Sphinx в 2008 году, он был принят многими крупными проектами, такими как Python, Django, Jinja, Flask, SaltStack, FreeIPA, SSSD, Bugzilla. Скорее всего, вы уже не раз сталкивались с результатами работы этого генератора на страницах сайта https://readthedocs.com

Указанный подход дает ряд преимуществ:

• За счет использования системы контроля версий упрощается процесс совместной работы и отслеживания изменений.

• Переход на язык разметки повышает структурированность документов и позволяет создавать файлы в разных целевых форматах.

• С помощью веток и тегов системы контроля версий можно сопровождать документацию сразу для нескольких версий продукта.

Вместе с тем, подход Docs as Code имеет и ряд существенных недостатков, с которыми придется смириться:

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

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

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

Клонируйте репозиторий

Если вы захотите внести вклад в развитие проекта, то начните с команды clone для загрузки репозитория с сервера:

git clone https://gitflic.ru/project/astra_aldpro/course.git

Создайте ветку и внесите изменения

Теперь вы можете командой cd перейти в каталог проекта:

cd course

Создайте новую ветку и переключитесь на нее с помощью команды checkout -b issue_N, где N - это номер проблемы из системы отслеживания ошибок проекта, например:

git checkout -b issue_24

Если эта ветка уже существует, переключиться на нее можно той же командой checkout без ключа -b:

git checkout issue_24

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

Внесите изменения в так называемый индекс командой add и зафиксируйте их командой commit. Описание коммита лучше начинать с глаголов “Добавил”, “Исправил” и т.п., которые описывают, что именно вы изменили, например:

git add .
git commit -m 'Добавил README.md'

Чтобы сохранить зафиксированные вами изменения на сервере, выполните команду push:

git push --set-upstream origin issue_24

Ключ --set-upstream с параметрами нужно использовать только один раз при первой отправке изменений на сервер, когда ветки issue_24 там еще нет. В дальнейшем будет достаточно только команды push:

git push

Создайте запрос на слияние

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

Для этого выберите свою ветку из списка и нажмите кнопку “Создать запрос”.

Далее нужно указать в качестве цели master-ветку и ввести название запроса. Рекомендуется сразу поставить флажок “Выполнить слияние одним коммитом (squash commit)”.

Если вы создали свою ветку совсем недавно и в master-ветку еще не были приняты изменения от других авторов, то конфликтов, скорее всего, не будет, и администратор проекта сможет “слить” их сразу после проверки.

Если же вы работали над изменениями довольно долго и за это время master-ветка претерпела значительные изменения, то для принятия запроса может потребоваться сначала устранить конфликты слияния.

Устранение конфликтов слияния

Для устранения конфликтов слияния вам нужно влить в свою ветку изменения из master и обработать конфликты вручную.

Переключитесь на master-ветку и загрузите последние обновления:

git checkout master
git pull

Переключитесь на свою ветку командой checkout и влейте в нее последние изменения из master-ветки командой merge:

git checkout issue_24
git merge master

Git уведомит вас о наличии конфликтов слияния. Список файлов, на которые нужно обратить внимание, вы сможете найти командой status:

git status

По завершению редактирования внесите изменения в индекс и зафиксируйте их как обычно командой commit:

git add .
git commit -m 'Устранил конфликты слияния issue_24'

Установка и настройка Sphinx для работы

Для изменения отдельных страниц достаточно будет простого редактора Kate или Visual Studio Code, но для сборки готовых документов в формате PDF или HTML нужно будет установить генератор Sphinx.

Для инсталляции Sphinx на ALSE 1.7.x сначала установите пакет python3-pip и выполните обновление системы управления пакетами pip:

sudo apt install python3-pip
sudo python3 -m pip install --upgrade pip

Далее установите Sphinx и сопутствующие модули, необходимые для генерации HTML-версии:

sudo python3 -m pip install sphinx sphinx_multitoc_numbering sphinx-rtd-theme myst-parser

где:

• sphinx - модуль генератора документации Sphinx;
• sphinx_multitoc_numbering - модуль для непрерывной нумерации разделов в нескольких оглавлениях при построении HTML-версии;
• sphinx-rtd-theme - используемая в проекте тема для HTML-версии;
• myst-parser - модуль для поддержки документов в разметке markdown (не является обязательным).

Для сборки документации в PDF-формате установите дополнительно следующие модули:

sudo apt install texlive-latex-extra texlive-lang-cyrillic latexmk python3-babel cm-super inotify-tools

где:

• texlive-latex-extra - коллекция плагинов для работы с LaTeX;
• texlive-lang-cyrillic - поддержка кириллических скриптов;
• latexmk - модуль, упрощающий генерацию документов с перекрекрестными ссылками;
• python3-babel - набор инструментов для локализации приложений Python;
• cm-super - шрифты Type 1? rjydthnbhjdfyyst bp METAFONT;
• inotify-tools - позволяет отслеживать изменения файловой системы (не является обязательным).

Для генерации документов воспользуйтесь утилитой make:

make html
make latexpdf

Когда вам в дальнейшем потребуется создать проект для работы над своей собственной документацией, выполните скрипт sphinx-quickstart в новой папке:

sudo python3 /usr/local/bin/sphinx-quickstart
...
> Separate source and build directories (y/n) [n]: y
> Project name: test
> Author name(s): test
> Project language [en]: ru
todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y
...

Быстрое погружение в синтаксис reStructuredText

Язык разметки текста reStructuredText (сокращение: ReST, расширение файла: .rst) позволяет не ломать голову над оформлением и сосредоточиться на структуре документа. При создании языка основными целями было достижение удобочитаемости, ненавязчивости и однозначности.

Язык ReST похож на Markdown, но предоставляет намного больше возможностей. Например, с помощью rst вы можете подключать содержимое из других файлов, автоматически строить оглавление, создавать перекрестные ссылки.

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

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

Заголовки

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

В качестве символов оформления могут быть использованы = - ~ " ^ # * : . ' _ +. За каждым из этих символов не закреплен какой-то определенный уровень заголовка, в reStructuredText используется другой подход. Уровень раздела определяется порядком использования стилей, и обычно рекомендуют следующий подход:

###########################################################
Название документа
###########################################################

***********************************************************
Название главы
***********************************************************

Заголовок H1 (Раздел, section)
===========================================================

Заголовок H2 (Подраздел, subsection)
-----------------------------------------------------------

Заголовок H3 (Подподраздел, subsubsection)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Заголовок H4 (Абзац, paragraph)
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Заголовок H5 (Абзац, paragraph)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Заголовок H6 (Абзац, paragraph)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Абзацы

Абзацы должны иметь одинаковый отступ от левой границы и отделяются друг от друга с помощью пустых строк:

Первый абзац. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Второй абзац. Ut enim ad minim veniam, quis nostrud exercitation ullamco
laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

Начертание

Чтобы сделать текст [*курсивом*], его нужно обозначить одним символом звездочки. Чтобы сделать текст [**жирным**], его нужно обособить двумя символами звездочки. Для выделения [``команд``] их нужно обособить двумя обратными кавычками. Создать подчеркнутый или зачеркнутый текст в reStructuredText, к сожалению, не получится.

Вы можете использовать директивы [:sup:`N`] и [:sub:`N`] для создания верхних и нижних индексов соответственно.

Формула Эйнштейна E = mc\ :sup:`2` , а формула воды H :sub:`2` O .

Вставка команды терминала

Для вставки команд терминала используйте директиву code-block с указанием языка разметки console, например:

.. code-block:: console

   localadmin@astra:~$ echo "$USER"
   localadmin

Если в коде будут переменные, например, $USER, то используйте двойные кавычки “$USER”.

Вставка исходного кода

Для вставки исходных кодов используйте директиву code-block с указанием языка программирования, например:

Для проверки версии и уровня защищенности используйте команды:

.. code-block:: python
   :linenos:
   :lineno-start: 10
   :emphasize-lines: 3,5

   def some_function():
       interesting = False
       print('This line is highlighted.')
       print('This one is not...')
       print('...but this one is.')

Могут быть использованы следующие параметры:

• linenos - Включает нумерацию строк.

• lineno-start - Устанавливает номер первой строки кода. Если параметр задан, нумерация строк включается автоматически.

• emphasize-lines - Позволяет выделить строки кода.

• caption - Устанавливает заголовок для блока

• name - Уникальное имя для возможности использования этого идентификатора в ссылках ref.

Ссылки на URI-адрес

Для создания ссылок используется следующий синтаксис [`текст ссылки <URI-адрес>`_], например:

Группа Астра — один из лидеров российского рынка информационных технологий,
`перейти на официальный сайт компании <https://astralinux.ru/>`_.

Нумерованные списки

Нумерованные списки создаются с помощью символа решетки с точкой #.:

#. Один
#. Два
#. Три

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

5. Пять
#. Шесть
#. Семь

Маркированные списки

Маркированные списки создаются с помощью символов звездочки * или дефиса -. Пробелы после маркера обязательны:

Список один:

* Один
* Два
* Три

Список два:

- Один
- Два
- Три

Вложенные списки

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

#. Первый уровень
    * Второй уровень
        * Третий уровень

Таблицы

Таблицу можно создать с помощью директив table, csv-table или list-table, например:

.. list-table:: Заголовок таблицы
  :name: идентификатор_таблицы
  :widths: 40 15 15 15 15
  :header-rows: 1
  :align: left

  * - Заголовок 1
    - Заголовок 2
    - Заголовок 3
    - Заголовок 4
    - Заголовок 5
  * - Строка 1, колонка 1
    - Строка 1, колонка 2
    - Строка 1, колонка 3
    - Строка 1, колонка 4
    - Строка 1, колонка 5
  * - Строка 2, колонка 1
    - Строка 2, колонка 2
    - Строка 2, колонка 3
    - Строка 2, колонка 4
    - Строка 2, колонка 5

Могут быть использованы следующие параметры:

• align - Горизонтальное выравнивание таблицы, допустимые значения “left”, “center” и “right”

• header-rows - Количество строк таблицы сверху, которые будут оформлены как заголовок. По умолчанию 0.

• stub-columns - Количество столбцов таблицы слева, которые будут оформлены как заголовок. По умолчанию 0.

• width - Ширина таблицы в пикселях или процентах от ширины страницы. Если параметр не задан, средства визуализации определяют ширину таблицы на основе ее содержимого или ширины столбца.

• widths - Список целочисленных значений, определяющий ширину столбцов. По умолчанию используются столбцы одинаковой ширины (100% ширины экрана / количество столбцов).

В документации reStructuredText упоминается, что в крайних версиях допустимо использовать служебное слово auto, но в текущей редакции Sphinx 5.3.0, доступной для Astra Linux, эта опция еще недоступна.

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

.. csv-table:: Заголовок таблицы
  :widths: 15, 10, 30
  :delim: ;
  :quote: "
  :file: test.csv

Содержимое файла при этом должно соответствовать по количеству колонок и использовать указанные символы-разделители:

"Заголовок 1"; "Заголовок 2"; "Заголовок 3"
"Строка 1, колонка 1"; "Строка 1, колонка 2"; "Строка 1, колонка 3"
"Строка 2, колонка 1"; "Строка 2, колонка 2"; "Строка 2, колонка 3"

Могут быть использованы следующие параметры:

• delim - Символ-разделитель для значений строки.

• encoding - Кодировка символов, по умолчанию None, что соответствует автоматическому распознаванию кодировки.

• escape - Символ, используемый для экранирования символов-разделителей. По умолчанию экранирующий символ не задан, поэтому символы-разделители могут быть экранированы тем же символом, например “В этой строке ““слово”” будет в кавычках”.

• file - Путь к локальному csv-файлу.

• url - Путь к csv-файлу, размещенному в Интернет. Задается в формате https://…

• quote - Символ для обособления значений, состоящих из нескольких слов.

Рисунки

Для вставки рисунков могут быть использованы директивы image и figure.

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

Директива image позволяет делать простую вставку рисунков:

.. image:: picture.png
   :width: 200
   :height: 100
   :scale: 50
   :alt: Альтернативный текст
   :align: right

Могут быть использованы следующие параметры:

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

• width - Ширина изображения в пикселях. На значение этого параметра влияет параметр scale. Например, если width=200 и scale=50, то данное сочетание эквивалентно width=100 без указания параметра scale. Ширину можно задать не только в пикселях, но и в процентах относительно ширины страницы.

• height - Высота изображения в пикселях, используемая для резервирования места или масштабирования изображения по вертикали.

• scale - Коэффициент масштабирования изображения в процентах, но символ % добавлять не нужно. Значение «100» соответствует полному размеру изображения, что эквивалентно отсутствию опции scale.

• align - Выравнивание изображения, эквивалентное атрибуту align тега из языка HTML. Значения “top”, “middle”, и “bottom” управляют вертикальным выравниванием изображения (относительно базовой линии текста), поэтому полезны только для изображений внутри текста, которые можно создать подстановкой. Значения “left”, “center”, и “right” управляют горизонтальным выравниванием изображения, позволяя изображению плавать и обтекать его текстом. Конкретное поведение зависит от используемого браузера или программного обеспечения для рендеринга.

• target - Превращает изображение в гиперссылку. Значением параметра быть URI (относительный или абсолютный) или внутренняя ссылка с суффиксом подчеркивания (например, objectname_).

• class - Устанавливает значение атрибута class для тега

Для вставки изображений внутрь текста можно использовать директиву подстановки:

Красный сигнал светофора |red_light| означает, что нужно остановиться, а зеленый |green_light| говорит о том, что можно идти.

.. |red_light| image:: red_light.png
   :align: top

.. |green_light| image:: green_light.png
   :align: bottom

Директива figure позволяет вставлять именованные иллюстрации:

.. figure:: picture.png
   :name: figure_name
   :scale: 50
   :alt: Альтернативный текст

   Заголовок рисунка (просто параграф текста)

Директива figure поддерживает все параметры директивы image и расширяет их список следующими возможностями:

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

• figclass - Устанавливает значение атрибута class для тега

• align - Задает горизонтальное выравнивание фигуры, с помощью чего можно создать обтекание рисунка текстом. Допустимые значения “left”, “center”, и “right”. Конкретное поведение зависит от используемого браузера или программного обеспечения для рендеринга.

Ссылки на таблицы и рисунки

Если таблице или рисунку было присвоено уникальное имя, то на эти объекты можно сослаться из текста с помощью директив ref и numref, где ref подставит заголовок объекта, а numref его порядковый номер в документе:

В качестве примера см. :numref:`picture_id` :ref:`picture_id`.

.. figure:: picture.png
   :name: picture_id
   :scale: 50

   Заголовок рисунка

Уникальное имя для создания ссылки можно присвоить и заголовку:

.. _target_header:

Целевой заголовок
============================

...

Подробнее см. :numref:`target_header` :ref:`target_header`

Горизонтальные разделители

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

Абзац текста. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

--------

Абзац текста. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

________

Абзац текста. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Математические формулы

Синтаксис reStructuredText позволяет вставлять формулы с помощью директивы math. Формулы отображаются корректно как в PDF документах, так и на веб-страницах, за что отвечает кроссбраузерная библиотека Mathjax для JavaScript.

Формула по центру страницы:

.. math::
   ЦПУ = 1 + \frac{3\ 000}{4\ 000} = 4

Формула по тексту :math:`ЦПУ = 1 + \frac{3\ 000}{4\ 000} = 4` абзаца.

Формула по тексту |cpu_example| абзаца через директиву подстановки replace.

.. |cpu_example| replace:: :math:`ЦПУ = 1 + \frac{3\ 000}{4\ 000} = 4`

Для быстрого составления формул можно воспользоваться онлайн редактором https://latexeditor.lagrida.com/

Оповещения

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

.. attention::

   Этот абзац из трех строк,
   будет оформлен как предупреждение
   с заголовком "внимание"

Допустимые виды оповещений:

• attention (внимание),
• caution (осторожно),
• danger (опасно),
• error (ошибка),
• hint (подсказка),
• important (важно),
• note (примечание),
• seealso (см. также),
• tip (совет),
• warning (предупреждение).

Язык, на котором будут представлены заголовки оповещений, зависит от значения параметра language в конфигурационном файле проекта conf.py

С помощью директивы admonition вы можете создавать пользовательские оповещения с произвольными заголовками:

.. admonition:: Примите к сведению
   :class: note

   Данное оповещение будет оформлено как примечание (note).

Комментарии и задачи

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

.. Первая строка многострочного комментария
   Вторая строка комментария

Если вы хотите оставить комментарий как задачу, чтобы вернуться к редактированию текста, то лучше воспользоваться модулем sphinx.ext.todo и задействовать инструкцию todo.

.. todo::
   Переформулировать этот абзац

Это позволит вам вывести все эти задачи одним списком с помощью инструкции todolist:

.. todolist::
   This directive is replaced by a list of all todo directives in the whole documentation, if

Вставка текста из другого файла

Синтаксис языка ReST позволяет включать в документ содержание других файлов. Например, вы можете воспользоваться для этого директивой include:

.. include:: document1.rst

Но для объединения документов в дерево страниц обычно используют директиву toctree:

.. toctree::
   :maxdepth: 3

   document1.rst
   document2.rst
   documentN.rst

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

Могут быть использованы следующие параметры:

• maxdepth - Глубина оглавления, сколько вложенных разделов требуется отобразить.

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

• caption - Заголовок, который должен быть указан перед оглавлением.

• name - Уникальное имя для возможности использования этого идентификатора в ссылках ref.

• titlesonly - Позволяет исключить из оглавления второй и последующий уровни заголовков из включаемых документов. Данный параметр не сказывается на работе билдера latexpdf.

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

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

Дополнительные настройки Visual Studio Code

Перенос по словам

Параграфы текста могут содержать несколько строк, поэтому для удобной работы с текстами нужно включить автоматический перенос слов. Сделать это можно с помощью команды меню “View \ Word Wrap (Alt+Z)”

Проверка орфографии

Для проверки орфографии требуется:

• установить плагин “Russian - Code Spell Checker”;

• открыть в меню страницу настроек “File \ Preferences \ Settings (Ctrl+Comma)”;

• установить для параметра “cSpell.language” значение “en,ru”.

Плагин reStructuredText

Вы можете существенно повысить свою производительность при редактировании документов reStructuredText, если установите одноименный плагин, который будет генерировать HTML-версию “на лету” и отображать ее в дополнительной панели редактора.

Для установки плагина вам необходимо:

• Открыть страницу View > Extentions

• С помощью строки поиска найти плагин по имени “reStructuredText”, производитель LeXtudio inc.

• Открыть страницу плагина и нажать кнопку “Install”

Для того, чтобы плагин заработал, вам нужно открыть папку документа, а не папку проекта, чтобы Visual Studio видел в корне файл conf.py Далее Visual Studio предложит установить еще несколько зависимых плагинов, после чего reStructuredText заработает.