Может ли исходный файл Java также быть действительным документом AsciiDo c с оглавлением? - PullRequest
Новая
       34

Может ли исходный файл Java также быть действительным документом AsciiDo c с оглавлением?

0 голосов
/ 28 мая 2020

Я провел несколько экспериментов с написанием программ, которые в то же время являются действительной документацией, которую можно отобразить как README, например, Github - это гарантирует, что фрагменты кода актуальны и действительны - и получил некоторые очень интересные результаты с помощью Markdown . К сожалению, этот формат не поддерживает автоматически сгенерированное оглавление, поэтому мы рассмотрели AsciiDo c, который поддерживает.

Мне удалось скопировать пример, используя :toc: macro (чтобы иметь возможность разместить его после вступительного резюме), а затем сделал его действительным Java, что по сути означает, что вы должны запустить файл с символами /*, но тогда я больше не могу сделать так, чтобы оглавление отображалось.

Фрагмент начинается с: 

= Asciidoctor PDF Theming Guide
Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
// Settings:
:idprefix:
:idseparator: -
:toc: macro
:experimental:
ifndef::env-github[:icons: font]
ifdef::env-github[]
:outfilesuffix: .adoc
:!toc-title:
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
:window: _blank
// Aliases:
:conum-guard-yaml: #
ifndef::icons[:conum-guard-yaml: # #]
ifdef::backend-pdf[:conum-guard-yaml: # #]
:url-fontforge: https://fontforge.github.io/en-US/
:url-fontforge-scripting: https://fontforge.github.io/en-US/documentation/scripting/
:url-prawn: http://prawnpdf.org

////
Topics remaining to document:
* line height and line height length (and what that all means)
* title page layout / title page images (logo & background)
////

[.lead]
The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file 
... blurb removed ...
/* (Experiment with asciidoc)

= Dagger 2 Hello World

// (Important:  As an experiment Main.java is also a valid markdown file copied unmodified to README.md, so only edit Main.java)

This project is a single file Hello World Dagger-2 Maven project for
Java 8 and later, while also being its own documentation written in AsciiDoc.

toc::[]

Мне кажется, что TO C работает, как ожидалось, только если файл начинается с со строками, проанализированными AsciiDo c, где он установлен и настроен. Если какой-либо вывод генерируется до битов конфигурации (например, комментарий Java), то TO C молча пуст.

Следовательно, я хотел бы знать, как мне это сделать правильно. Все, что мне нужно, это функциональный макрос toc::[] в файле, начинающийся с /*

1 Ответ

1 голос
/ 04 июня 2020
Файлы разметки

Asciido c не являются исходными файлами Java. Хотя я понимаю, что это будет убедительная комбинация форматов, такой возможности не существует.

Чтобы поддерживать актуальность исходных файлов, ваши исходные файлы Asciido c могут использовать директиву include для включения исходного файла. См .: https://asciidoctor.org/docs/user-manual/#include -directive

Чтобы включить, скажем, один метод, вы можете использовать теги, чтобы отметить начало и конец реализации метода, а затем вы можете включить этот тег -delimited раздел кода, например: 

[source,java]
----
include::path/to/source.java[tag="method-x"]
----

Обратите внимание, что если путь к источнику Java, который вы хотите включить, находится за пределами текущего каталога, вам может потребоваться изменить безопасный режим соответствующим образом: https://asciidoctor.org/docs/user-manual/#running -сциидоктор-надежно

...