Skip to content

Add AsciiDoc build infrastructure #862

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 23, 2024
Merged

Add AsciiDoc build infrastructure #862

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitattributes
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,3 +181,4 @@ cdtOptions text
*.py text
*.xhtml text
*.entitlements text
*.adoc text
2 changes: 2 additions & 0 deletions doc/org.eclipse.cdt.doc.user/.asciidoctorconfig.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
// support image rendering within the Asciidoctor Editor (#873)
:imagesdir: {asciidoctorconfigdir}/images
Copy link
Contributor Author

@jld01 jld01 Jul 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We instruct the Asciidoctor Editor to look for images in the images folder of the project. Example:

image

1 change: 1 addition & 0 deletions doc/org.eclipse.cdt.doc.user/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
/html/
/workspace/
5 changes: 3 additions & 2 deletions doc/org.eclipse.cdt.doc.user/build.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
###############################################################################
# Copyright (c) 2000, 2011 IBM Corporation and others.
# Copyright (c) 2000, 2024 IBM Corporation and others.
#
# This program and the accompanying materials
# are made available under the terms of the Eclipse Public License 2.0
Expand Down Expand Up @@ -38,7 +38,8 @@ bin.includes = about.html,\
intro/,\
notices.html,\
book.css,\
index*/
index*/,\
html/

bin.excludes = build.properties,\
customBuildCallbacks.xml
Expand Down
22 changes: 22 additions & 0 deletions doc/org.eclipse.cdt.doc.user/help.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,3 +60,25 @@ div.linux {display:none;}
.bold {font-weight:600;}
.linethrough {text-decoration: line-through;}
.underline {text-decoration: underline;}

/* AsciiDoc support based on Asciidoctor default stylesheet | MIT License | http://asciidoctor.org (#873) */
p.tableblock { margin: 0 }
table.tableblock tr th, table.tableblock tr td { padding: 0.3em }
table.tableblock, th.tableblock, td.tableblock { border: 0 solid #dedede }
table.grid-all>thead>tr>.tableblock, table.grid-all>tbody>tr>.tableblock { border-width: 0 1px 1px 0 }
table.grid-all>tfoot>tr>.tableblock { border-width: 1px 1px 0 0 }
table.grid-cols>*>tr>.tableblock { border-width: 0 1px 0 0 }
table.grid-rows>thead>tr>.tableblock, table.grid-rows>tbody>tr>.tableblock { border-width: 0 0 1px 0 }
table.grid-rows>tfoot>tr>.tableblock { border-width: 1px 0 0 0 }
table.grid-all>*>tr>.tableblock:last-child, table.grid-cols>*>tr>.tableblock:last-child { border-right-width: 0 }
table.grid-all>tbody>tr:last-child>.tableblock, table.grid-all>thead:last-child>tr>.tableblock, table.grid-rows>tbody>tr:last-child>.tableblock, table.grid-rows>thead:last-child>tr>.tableblock { border-bottom-width: 0 }
table.frame-all { border-width: 1px }
table.frame-sides { border-width: 0 1px }
table.frame-topbot { border-width: 1px 0 }
th.halign-left, td.halign-left { text-align: left }
th.halign-right, td.halign-right { text-align: right }
th.halign-center, td.halign-center { text-align: center }
th.valign-top, td.valign-top { vertical-align: top }
th.valign-bottom, td.valign-bottom { vertical-align: bottom }
th.valign-middle, td.valign-middle { vertical-align: middle }
div.listingblock pre { padding: 0.7em }
28 changes: 27 additions & 1 deletion doc/org.eclipse.cdt.doc.user/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2011, 2021 Contributors to the Eclipse Foundation
Copyright (c) 2011, 2024 Contributors to the Eclipse Foundation

This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
Expand Down Expand Up @@ -40,6 +40,32 @@
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>3.0.0</version>
<executions>
<execution>
<id>adoc-to-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<outputDirectory>${project.basedir}/html</outputDirectory>
<attributes>
<icons>font</icons>
<imagesdir>../images</imagesdir>
Copy link
Contributor Author

@jld01 jld01 Jul 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

<linkcss />
<reproducible />
<source-highlighter>coderay</source-highlighter>
<stylesheet>../help.css</stylesheet>
<toc>macro</toc>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>

Expand Down
65 changes: 65 additions & 0 deletions doc/org.eclipse.cdt.doc.user/src/asciidoc/example.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
////
Copyright (c) 2024 John Dallaway and others
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/

SPDX-License-Identifier: EPL-2.0

Contributors:
John Dallaway - initial example AsciiDoc content (#873)
////

// support image rendering and table of contents within GitHub
ifdef::env-github[]
:imagesdir: https://raw.githubusercontent.com/eclipse-cdt/cdt/main/doc/org.eclipse.cdt.doc.user/images
Copy link
Contributor Author

@jld01 jld01 Jul 11, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

:toc:
:toc-placement!:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need these github-specific directives to support presentation of a table of contents in github.

endif::[]

= Example document

toc::[]

== Images

Example image:

image:search.png[Search dialog]

== Tables

Example table:

[options="header"]
|===
|Column A |Column B
|Cell 1A |Cell 1B
|Cell 2A |Cell 2B
|Cell 3A |Cell 3B
|===

== Lists

Example list:

. Item A
. Item B
. Item C

== Code blocks

Example code block:

[source,c]
----
#include <stdio.h>

int main (int argc, char* argv[]) {

printf("Hello World!\n");
return 0;

}
----
Loading