Вопрос или проблема
Допустим, у меня есть:
class Hello:
"""Пример класса."""
world: str
"""Это единственное поле в :py:class:`Hello`."""
Документация написана с использованием формата ReST, который предназначен для использования с Sphinx.
В VS Code, если я рефакторю Hello на что-то другое, ссылка py:class:`Hello не будет обновлена. Есть ли что-то, что я могу сделать (либо в настройках, либо с помощью расширения), чтобы это обновление произошло?
Ответ или решение
Для переименования переменной в Python и обновления ее упоминания в документации, оформленной в формате ReST, в Visual Studio Code, вы можете воспользоваться встроенными средствами редактора, а также специальными расширениями. Вот подробное руководство:
Шаг 1: Установка расширений
-
Установите расширение Python: Убедитесь, что у вас установлено официальное расширение Python от Microsoft. Это расширение предоставляет поддержку работы с Python и позволяет редактировать код, выполнять рефакторинг и т.д.
- Установите расширение для Sphinx: Для того чтобы улучшить поддержку документации в формате ReST, установите расширение, такое как "reStructuredText", которое поможет с подсветкой синтаксиса и автозавершением.
Шаг 2: Переименование переменной
-
Откройте файл с кодом: Найдите файл, в котором вы хотите переименовать класс (в данном случае,
Hello). - Используйте функцию "Переименовать": Щелкните правой кнопкой мыши на имени класса и выберите "Переименовать" (или нажмите
F2). Введите новое имя для класса и нажмитеEnter. Это обновит все упоминания класса в вашем коде.
Шаг 3: Обновление документации
К сожалению, встроенная функция переименования в VS Code не обновляет ссылки на класс в документации, оформленной в формате ReST. Однако вы можете вручную обновить документацию следующим образом:
-
Поиск и замена: Используйте функцию поиска в вашем проекте (нажмите
Ctrl + Shift + F), чтобы найти все упоминания:py:class:Hello“. Замените её на новое имя класса. - Обновление комментариев: Не забудьте проверить и обновить все значения, которые могли ссылаться на устаревшее имя класса в вашем коде и комментариях.
Дополнительные рекомендации
-
Используйте скрипты для автообновления: Если у вас есть много упоминаний в документации, вы можете написать скрипт на Python, который пройдет по вашим файлам и заменит старое имя на новое. Это может оказаться полезным, если у вас большое количество документации.
-
Настройки Sphinx: Убедитесь, что вы используете последние версии Sphinx и его зависимостей. Это поможет избежать проблем с генерацией документации.
- Проверка корректности работы: После замены имени класса проверьте, что документация обновилась корректно, выполнив сборку документации с помощью Sphinx.
С помощью этих шагов вы сможете успешно переименовать класс и обновить соответствующие упоминания в документации, используя возможности Visual Studio Code и некоторые внешние инструменты.