Создание документации Python с помощью doxygen приводит к неработающим ссылкам на функции - PullRequest
Новая
       22

Создание документации Python с помощью doxygen приводит к неработающим ссылкам на функции

0 голосов
/ 07 мая 2018

Версия Doxygen: 1.8.12 - Конфигурация по умолчанию

Я создавал документацию по Python с использованием Doxygen. Это хорошо сработало при документировании занятий. Однако теперь я построил несколько модулей с некоторыми функциями, которые я документирую следующим образом: 

 ## @file
 #  my module comment

 ##
 # my function
 # @return 0
 def func():
     return 0

Затем создается вкладка Files, где я могу найти файлы моего модуля. Однако, когда я нажимаю на них, список функций отображается в виде ссылок, которые не работают (при нажатии на страницу перенаправляется на себя), а фактические определения модуля добавляются в конце страницы.

Что я должен сделать, чтобы избежать неработающих ссылок, возможно, поведение, подобное тому, что происходит с классами (где функции имеют отдельный HTML), более желательно

==== ==== UPDATE При проверке сгенерированного HTML-кода, очевидно, ссылки указывают на адрес в следующем стиле: 

Documtenation/myfilepy.html#some_hash

Принимая во внимание, что фактические разделы страницы имеют идентификаторы в этом стиле: 

 file_some_hash

правильный способ вызова ссылок должен быть: 

Documentation/myfilepy#file_some_hash

Как сделать так, чтобы doxygen пропустил file_ или правильно сгенерировал ссылки?

1 Ответ

0 голосов
/ 07 мая 2018

Я только что попробовал с 1.8.12 (а также с 1.8.14 текущей и предпочтительной версией, а также с текущей версией разработки).Я вижу на странице Files ссылку на myfile.py (когда я удалил слово myfile из команды \file).На странице myfile.py я вижу 1 ссылку на myfile.func, но ссылка никуда не ведет.

При попытке сделать то же самое с функцией C она работает.Глядя в код HTML, который я вижу (для C), в части Functions: 

<a class="el" href="bb_8c.html#a916cba588658b3be41b91489a560a664">c_func</a>

и 

<a href="#a916cba588658b3be41b91489a560a664">More...</a>

и далее в части Function Documentation: 

<a id="a916cba588658b3be41b91489a560a664"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a916cba588658b3be41b91489a560a664">&#9670;&nbsp;</a></span>c_func()</h2>

Просмотр HTML-кода, который я вижу (для Python), в части Functions: 

<a class="el" href="myfile_8py.html#a3f1962c8fd3ce4b252b1015bf4cb3c32">myfile.func</a>

и 

<a href="myfile_8py.html#a3f1962c8fd3ce4b252b1015bf4cb3c32">More...</a>

и далее вFunction Documentation part: 

<a id="file_a3f1962c8fd3ce4b252b1015bf4cb3c32"></a>
<h2 class="memtitle"><span class="permalink"><a href="#file_a3f1962c8fd3ce4b252b1015bf4cb3c32">&#9670;&nbsp;</a></span>func()</h2>

Очевидно, что file_ в версии Python не должно присутствовать (file_ не имеет ничего общего с именем файла, так как имя файла, подобное something.py, дает тот же результат).

Примечание: я нашел в коде, memberdef.cpp: 

// member is in a namespace, but is written as part of the file documentation
// as well, so we need to make sure its label is unique.

Редактировать: основываясь на предложении, которое я уже сделал в комментариях, я только что только что выдвинул это какпредлагаемый патч для github (запрос на извлечение 720, https://github.com/doxygen/doxygen/pull/720).

...