Можно даже без заголовка в плейсхолдере, а только заголовок в инклюде

SEO для документации.
Read the Docs опубликовали руководство по search engine optimization для документации. В отличие от руководств по SEO «вообще», в этом есть конкретные примеры разметки reStructuredText. Например, я ни разу не заполнял метаданные, а теперь буду:

 meta::
    :description lang=en:
        Adding additional CSS or JavaScript files
        to your Sphinx documentation can let
        you customize the look and feel of your
        docs or add additional functionality.

Читать тут: https://docs.readthedocs.io/en/latest/guides/technical-docs-seo-guide.html

Toctree не работает «вверх» вот почему: пути к файлам становятся URL'ами страниц. И конечно, в URL'е не может быть `example.com/../somedir/somefile`.

А кроме инклюдов ещё можно делать симлинки директорий. Например, в каждом проекте вы делаете симлинк ./source/foo на внешнюю директорию ../foo. Теперь в индексе можно указывать прямой путь к файлам.

Но это сработает только на Linux/OSX, а в Windows — нет.

Передам вопрос человеку из команды документирования Kotlin :)

Привет! Официальный ответ на этот вопрос - KDoc + Dokka: https://kotlinlang.org/docs/reference/kotlin-doc.html

вот странно, все ругают маркдаун за отсутствие стандарта, а сами делают документацию на базе своего диалекта маркдауна

не проще было взять asciidoc, rst или org-mode?

KDoc uses the regular Markdown syntax

Да, но расширен

а, чет проглядел, виновен

Предыстория создания мне не известна, если правда интересно, то вероятнее всего получить ответ в Котлиновском Slack.

Прочитал статью про то, как рендерить документацию на Sphinx с помощью React. Ничего не понял. :)

https://medium.com/@mtiller/rendering-sphinx-documentation-with-react-95b785293a76

​​Не писать на слайдах мелким шрифтом, вот что делать!

Конвертировать DOCX в reST, Markdown или AsciiDoc вместе с изображениями:

 pandoc -f docx --extract-media images -t rst -o document.rst document.docx 
pandoc -f docx --extract-media images -t markdown -o document.md document.docx
pandoc -f docx --extract-media images -t asciidoc -o document.adoc document.docx

Изображения будут в директории images. В любой разметке сразу будут правильные ссылки на них.

 pandoc -f docx --extract-media images -t rst -o document.rst document.docx 
pandoc -f docx --extract-media images -t markdown -o document.md document.docx
pandoc -f docx --extract-media images -t asciidoc -o document.adoc document.docx

Чот с кодировкой

 pandoc -f docx --extract-media images -t rst -o document.rst document.docx 
pandoc -f docx --extract-media images -t markdown -o document.md document.docx
pandoc -f docx --extract-media images -t asciidoc -o document.adoc document.docx

Комментарии не экспортируются.

​​А я думал, это называется документация.

Аттракцион «почувствуй себя нубом».

Читаю в доке Jekyll про то, как использовать шаблоны Liquid прямо в исходниках страниц. Это помогает раскладывать структурированные данные в HTML и переиспользовать готовые блоки с помощью include. И это очень удобно.

В сотый раз грущу, что такое есть в Jekyll, Hugo, вообще где угодно, кроме Sphinx.

В отчаянии гуглю и первой ссылкой нахожу статью 2016 года, в которой Eric Holscher в десять строк кода на Python добавляет эту фичу в Sphinx.

Эрик, ну как я теперь с этим буду жить?

Уже попробовал?