Add AsciiDoc build infrastructure #862
Conversation
| @@ -0,0 +1,8 @@ | |||
| ifdef::env-github[] | |||
| :imagesdir: https://raw.githubusercontent.com/eclipse-cdt/cdt/main/doc/org.eclipse.cdt.doc.user/images | |||
There was a problem hiding this comment.
This is a github-specific directive to locate images in the specified location for the purpose of rendering documents in github itself. Note that new images added by a PR won't yet exist at the required location.
Example of github rendering: https://github.com/jld01/cdt/blob/adoc-example/doc/org.eclipse.cdt.doc.user/src/asciidoc/example.adoc
| <outputDirectory>${project.basedir}/html</outputDirectory> | ||
| <attributes> | ||
| <icons>font</icons> | ||
| <imagesdir>../images</imagesdir> |
There was a problem hiding this comment.
The asciidoctor-maven-plugin is configured to emit HTML to the html folder of the project and look for images at ../images relative to the html folder. We can observe the plugin in operation at: https://github.com/eclipse-cdt/cdt/actions/runs/9892171366/job/27324211365#step:7:10840
| // :imagesdir: {asciidoctorconfigdir}/images | ||
| // | ||
| // For more information please take a look at https://github.com/de-jcup/eclipse-asciidoctor-editor/wiki/Asciidoctor-configfiles | ||
| :imagesdir: {asciidoctorconfigdir}/images |
There was a problem hiding this comment.
We instruct the Asciidoctor Editor to look for images in the images folder of the project. Example:
|
@jonahgraham, @Torbjorn-Svensson, @jjohnstn and all, following our discussion on the CDT project call this week, this PR is intended to illustrate how we could integrate AsciiDoc content within the existing CDT user documentation plugin for the purpose of adding missing topics and gradually migrating existing topics over time. Comments are welcome. If we are all happy with this approach, we could start by adding topics relating to core build. |
|
This looks great - thanks @jld01 An early target for docs would be the current contents of https://github.com/eclipse-cdt/cdt-lsp/blob/master/README.md - although maybe that should be kept in a (new) org.eclipse.cdt.lsp.docs bundle? cc: @ghentschke |
| ifdef::env-github[] | ||
| :imagesdir: https://raw.githubusercontent.com/eclipse-cdt/cdt/main/doc/org.eclipse.cdt.doc.user/images | ||
| :toc: | ||
| :toc-placement!: |
There was a problem hiding this comment.
We need these github-specific directives to support presentation of a table of contents in github.
doc/org.eclipse.cdt.doc.user/pom.xml
Outdated
| <linkcss /> | ||
| <source-highlighter>coderay</source-highlighter> | ||
| <stylesdir>..</stylesdir> | ||
| <stylesheet>help.css</stylesheet> |
There was a problem hiding this comment.
We use the existing CDT help stylesheet
jld01
force-pushed
the
adoc-example
branch
6 times, most recently
from
3d799c2 to
4ce20c6
Compare
|
@jonahgraham this is all working well now. A few additions to our common stylesheet are required to support Asciidoctor-generated HTML tables and code blocks. Are you OK with the MIT license on the definitions brought in from the default Asciidoctor stylesheet? |
|
@jonahgraham I have marked this as ready for review now. I have left the |
|
I have received confirmation from @jonahgraham that the MIT-licensed CSS definitions are OK. |
|
Everything is now in place to create CDT user documentation in AsciiDoc format and build it with Maven. The build system will generate an HTML file under All AsciiDoc files should include the GitHub rendering support, as illustrated in the example.adoc file. During development, the HTML files may be generated locally using: |
Resolves #873