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: Я не тестировал, поэтому ярлык может пересекаться с фактом, за которым следует стандартное содержимое, а не стандартное.

  • Разбор .rst файлов с программными директивами Sphinx
  • Как сделать внутреннюю гиперссылку в документации sphinx
  • : синопсис: не работает в автомодуле Sphinx
  • Sphinx-doc: автомодуль: с импортом макетов
  • Как заставить Sphinx уважать импорт классов в пакет с __init__.py
  • Выход Sphinx pdf: апострофы в источнике python заменяются одиночными кавычками
  • Значения сфинксов для атрибутов, указанных как Нет
  • Документ python с использованием Eclipse / Pydev
  • Python - лучший язык программирования в мире.