Sphinx's .. include :: директива и "дублировать ярлык"

Я пытаюсь использовать Sphinx 's .. include:: директиву для включения документов из одного файла в другой файл, чтобы избежать дублирования исходного текста документов. Раздел, который я включаю, находится в configuration.rst (он является частью справочных документов для настроек конфигурации) и содержит некоторые метки для перекрестной ссылки на каждый параметр конфигурации:

 .. start_config-authorization .. _ckan.auth.anon_create_dataset: ckan.auth.anon_create_dataset ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Example:: ckan.auth.anon_create_dataset = False Default value: ``False`` Allow users to create datasets without registering and logging in. .. _ckan.auth.create_unowned_dataset: ckan.auth.create_unowned_dataset ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ... .. end_config-authorization 

В другом файле ( authorization.rst ) я включаю только настройки configuration.rst авторизации из inline в config.rst, например:

 .. include:: /configuration.rst :start-after: start_config-authorization :end-before: end_config-authorization 

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

 doc/configuration.rst:224: WARNING: duplicate label ckan.auth.anon_create_dataset, other instance in doc/authorization.rst 

Пока перекрестные ссылки не кажутся сломанными, если я поставлю:

 :ref:`ckan.auth.anon_create_dataset` 

в третьем файле это правильно создает ссылку на определение ckan.auth.anon_create_dataset в configuration.html (а не на его копии в authorization.html ).

Безопасно ли просто игнорировать или заглушать эти повторяющиеся предупреждения на этикетках и ожидать, что все ссылки перекрестных ссылок будут связаны с configuration.html ? Или я должен найти другой способ сделать это?

2 Solutions collect form web for “Sphinx's .. include :: директива и "дублировать ярлык"”

Существует два способа решить эту проблему: переключитесь на другое расширение (* .inc) или добавьте любые conf.py файлы в exclude_patterns в conf.py

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

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

Ps: Я не тестировал, поэтому ярлык может пересекаться с фактом, за которым следует стандартное содержимое, а не стандартное.

  • Создание макросов LaTeX в Sphinx
  • Сфинкс, лучшие практики
  • Использование sphinx с Markdown вместо RST
  • Использование Sphinx с расширением C с добавлением distutils
  • Программа командной строки Python: создание man-страницы из существующей документации и включение в дистрибутив
  • Как опустить значения переменных на Sphinx?
  • Многострочное описание описания параметра в docstring python
  • Включить URL-адреса Django в документацию Sphinx?
  • Можно ли переопределить autodoc Sphinx для определенных функций?
  • Документ python с использованием Eclipse / Pydev
  • Sphinx: список функций в модуле
  • Python - лучший язык программирования в мире.