docs icon indicating copy to clipboard operation
docs copied to clipboard
verified publisher icon yandex-cloud

После генерации локальной документации (например, чтоб подготовить pull request) в ссылках не хватает ".html"

Open Nakilon opened this issue 3 years ago • 2 comments

В README есть информация о том, как документацию собирать, но не ясно, как правильно ее смотреть. Потому что если, например, открыть ru/overview/index.html, то из всех ссылок на разделы работает только одна, а остальные (например ru/overview/concepts/services) ведут вникуда, пока руками не добавишь .html.

P.S.: другие проблемы:

  1. Собирается долго, и я не вижу в https://ydocs.tech/ru/tools/docs/settings указания, как выбрать или исключить что-нибудь по маске. Если в -i передать подпапку, то какие-то макросы не работают в рез-тате. Если тупо удалить толстые подпапки, то в конце линтер много ругается на битые ссылки.
  2. По всей видимости, список файлов на входе собирается на лету, поэтому если выполнять команду внутри репозитория (как это чаще всего успешно и делается, например, в случаях С и make) с -i . -o docs-gen, то оно входит рекурсию и падает.

Nakilon avatar Mar 26 '22 10:03 Nakilon

Привет!

  1. Поправим отсутствие расширение .html у ссылок на разводящей при локальной сборке. Проблема наблюдается только там. Cмотреть документацию можно, открыв любую страницу из выходной директории, а также навигируясь через оглавление. На PR также создается стенд, ссылка на него оставляется в комментарии.
  2. Планируем прикрутить кеш, чтобы отслеживать файлы в директориях, в которых не было изменений и не собирать их повторно
  3. Запускать с -i . -o docs-gen неправильно, перед сборкой входная директория очищается от лишних файлов, чтобы в результирующей директории были только используемые файлы. Указание результирующей директории внутри входной директории приведет к удалению результирующей директории до начала сборки и произойдет ошибка. Запускать нужно так, как это указано в README, т.e yfm -i docs -o docs-gen или yfm -i . -o ../docs-gen. На стороне утилиты добавим валидацию, что выходная директория указана внутри входной

yndx-birman avatar Apr 18 '22 13:04 yndx-birman

  1. О, стенд -- это классно, я сразу не заметил.
  2. Да, должно сработать, если в Yandex Flavored Markdown нет каких-нибудь тегов, которые подтягивают контент из страницы, на которую ссылаются.
  3. "перед сборкой входная директория очищается" -- этого не знал, м.б. имеет смысл дописать в README или https://ydocs.tech/ru/tools/docs/

Nakilon avatar Apr 18 '22 13:04 Nakilon