Форматирование кода для системы ReadTheDocs - PullRequest
Новая
       10

Форматирование кода для системы ReadTheDocs

0 голосов
/ 03 июля 2019

Я использую Впервые прочитайте документы .Я пишу документы для системы командной строки, и мои "примеры кода" включают в себя журнал вывода оболочки.Вывод оболочки в конечном итоге выглядит следующим образом

image of shell output that read the docs has attempted to format as though it was source code resulting in some weird choices

То есть - служба (или я ее использую?) Пытается отформатировать этот примервыполнение команды оболочки, как если бы это был исходный код, и обрабатывает magento2:generate, как если бы это была константа класса.

Могу ли я контролировать, какие блоки кода получают форматирование исходного кода при чтении документов?Я попытался не задавать базовый язык в админке, но, похоже, это не дает эффекта.Или это то, что мне нужно контролировать на уровне mkdocs сфинкса?(прочитайте документацию, превратив файлы markdown или sphinx в красивые HTML-файлы) Или что-то еще?Или мне не повезло?

1 Ответ

2 голосов
/ 09 июля 2019

Вам необходимо определить «язык» блока кода в исходном документе.И Sphinx, и MkDocs попытаются угадать язык, что часто достаточно хорошо.Однако, иногда, он будет угадывать неправильно и приводить к странной подсветке.Чтобы избежать этого, обе реализации предоставляют механизм для ручного определения языка каждого блока кода.

Sphinx

Для Sphinx вы можете использовать директиву code-block ивключите «язык» блока: 

.. code-block:: console

    You shell commands go here

В приведенном выше примере я использовал console для сеанса оболочки .Псевдоним shell-session также будет работать.Обратите внимание, что альтернативный лексер bash (и его псевдонимы: sh, ksh, zsh и shell) не совсем подходит для использования в сценарии оболочки, тогда каквы отображаете как команду, так и выходные данные в сеансе оболочки.

Полный список поддерживаемых кодов языка можно найти в документации Pygments.

MkDocs

MkDocs использует расширение Fenced Code Block Markdown для определения «языка» блока кода: 

``` shell
Your shell commands go here
```

Поскольку MkDocs использует highlight.js вместо Pygments список поддерживаемых языков отличается.Поэтому я использовал shell (для сеанса оболочки) в приведенном выше примере.

...