- Prerequisites:
-
AsciiDoctor RubyGem can be installed with the following command:
gem install asciidoctor
- Generate Eclipse Help
-
cd docs/org.eclipse.n4js.doc mvn -Dtycho.mode=maven verify - HTML for Web:
-
(Requires AsciiDoctor RubyGem)
cd docs/org.eclipse.n4js.doc/src ./build.sh # Running the script with the -p flag opens the pages in a browser: ./build.sh -p
- Language Specification:
-
(Requires AsciiSpec custom tool)
cd docs/org.eclipse.n4js.spec ./build.sh # Running the script with the -p flag opens the pages in a browser: ./build.sh -p
Contributions to the source code and documentation of N4JS are highly encouraged. Updating, maintaining and improving documentation can be done by experts or complete beginners alike. Bring your experience or fresh perspectives to enrich help resources that assist N4JS developers everywhere.
To contribute or improve N4JS help, fork the N4JS repo, create a pull request with edited or new AsciiDoc files in the source folder and your contribution will be reviewed for inclusion.
All documentation for N4JS is written in AsciiDoc (.adoc format) and is deployed using a single-source toolchain described below.
The source documentation is located in the N4JS repository at:
The IDE is built using Apache Maven and running mvn verify builds the N4JS IDE including documentation at the following directory: n4js/docs/org.eclipse.n4js.doc/target.
The documentation plugin can be run as a standalone module by navigating to n4js/docs/org.eclipse.n4js.doc and running
mvn -Dtycho.mode=maven verify
The N4JS documentation plugin at n4js/docs/org.eclipse.n4js.doc contains user guides, tutorials and feature articles.
These files are used for the public N4JS project pages and the bundled Eclipse help.
A brief overview of the docs plugin looks like the following:
n4js/docs/org.eclipse.n4js.doc/
├── help-pages.txt
├── pom.xml
├── plugin.xml
├── src
│ ├── docs
│ │ ├── documentation
│ │ │ └── tutorial.adoc
│ │ ├── features
│ │ │ └── testing.adoc
│ │ └── releases
│ │ └── reporting-bugs.adoc
│ └── styles
│ └── n4js-adoc.css
└── toc.xml-
pom.xml - Describes the build of the
org.eclipse.n4js.docplugin. -
plugin.xml - Describes how the plugin extends the platform and implements functionality.
-
help-pages.txt - A list containing the paths of the target HTML files. This is used to generate the toc.xml.
-
toc.xml - Table Of Contents; contains a structured index of the help pages so they may be registered online or within the N4JS IDE
The Eclipse Help bundled with the N4JS IDE is a collection of HTML files accompanied by a toc.xml that lists their hierarchy.
In the Maven build, the POM at n4js/docs/org.eclipse.n4js.doc/pom.xml is configured to execute these plugins in the following order:
-
The
asciidoctor-maven-pluginconverts source AsciiDoc files (srcfolder) to HTML (targetfolder). -
An
antrun-plugincreates a .txt file containing the paths to the generated HTML pages calledhelp-pages.txt. -
The
geneclipsetoc-maven-pluginsearches for headings in the generated HTML in thetargetfolder and creates a structuredtoc.xmlbased on this hierarchy that the N4JS IDE can index.
For generating PDF and EPUB from the source AsciiDoc files, the addition of the following dependencies are required in the asciidoctor-maven-plugin:
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>${asciidoctorj.pdf.version}</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-epub3</artifactId>
<version>${asciidoctor-epub3.version}</version>
</dependency>AsciiDoc is a syntax and file format (.adoc).
AsciiDoctor is the associated toolchain for converting and processing AsciiDoc files. It is written in Ruby and is published to RubyGems.org.
- Resources:
-
AsciiDoc files can be written in any text editor and should (for our documentation) be saved with the
.adocextension. The following are two useful guides for writing AsciiDoc: