|
1 | | -:toc: right |
| 1 | += devonfw-docgen |
2 | 2 |
|
3 | | -= devonfw Documentation Generator |
4 | | -The devonfw community |
5 | | -${project.version}, ${buildtime}: Subtitle {doctitle} |
6 | | - |
7 | | -:toc: |
8 | | -toc::[] |
| 3 | +`devonfw-docgen` is a tool that can generate a complete and self-contained documentation as PDF, ePub or HTML from Asciidoc pages. |
9 | 4 |
|
10 | 5 | image:https://img.shields.io/github/license/devonfw/devon-docgen.svg?label=License["Apache License, Version 2.0",link=https://github.com/devonfw/devon-docgen/blob/develop/LICENSE] |
11 | 6 | image:https://img.shields.io/maven-central/v/com.devonfw.tools/devon-docgen.svg?label=Maven%20Central["Maven Central",link=https://search.maven.org/search?q=g:com.devonfw.tools+a:devon-docgen] |
12 | 7 | image:https://travis-ci.org/devonfw/devon-docgen.svg?branch=master["Build Status",link="https://travis-ci.org/devonfw/devon-docgen"] |
13 | 8 |
|
14 | | -DocGen is a tool that can generate a complete and self-contained documentation as PDF and HTML from Asciidoc wiki pages. |
15 | | - |
16 | | -== Features |
17 | | -With DocGen you can |
18 | | - |
19 | | -* maintain documentation on github wiki as individual pages using http://www.methods.co.nz/asciidoc[asciidoc] based on our xref:guidelines[guidelines]. |
20 | | -* generate a single and self-contained document as `PDF` or `HTML` from it |
21 | | -* convert links between wiki pages into document internal links |
22 | | -* have a single table of contents per complete document as well as per wiki page |
23 | | - |
24 | | -== Setup |
25 | | - |
26 | | -1. Clone your github wiki using git to your local machine |
27 | | -2. Create a pom.xml in the cloned wiki directory with the following content: |
28 | | -+ |
29 | | -```xml |
30 | | -<project xmlns="http://maven.apache.org/POM/4.0.0" |
31 | | - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
32 | | - xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> |
33 | | - |
34 | | - <modelVersion>4.0.0</modelVersion> |
35 | | - <parent> |
36 | | - <groupId>com.devonfw.tools</groupId> |
37 | | - <artifactId>devon-docgen</artifactId> |
38 | | - <version>4.0.0</version> |
39 | | - </parent> |
40 | | - <groupId>my.group.id</groupId> |
41 | | - <artifactId>my-artifact-id</artifactId> |
42 | | - <version>1.0.0-SNAPSHOT</version> |
43 | | - <packaging>jar</packaging> |
44 | | - <name>My Cool Wiki</name> |
45 | | - |
46 | | - <properties> |
47 | | - <docgen.wiki.page>my-main-page</docgen.wiki.page> |
48 | | - </properties> |
49 | | - |
50 | | - <!-- run "mvn package -Doutput.format=pdf" and get the PDF result in target/generated-docs/*.pdf --> |
51 | | - |
52 | | - <!-- run "mvn package -Doutput.format=html" and get the HTML5 result in target/generated-docs/* --> |
53 | | - |
54 | | -</project> |
55 | | -``` |
56 | | -3. Add, commit and push it to github: |
57 | | -+ |
58 | | -[source,cmd] |
59 | | --------- |
60 | | -git add pom.xml |
61 | | -git commit -m "added pom.xml for docgen" |
62 | | -git push |
63 | | --------- |
64 | | -4. Optional custom theme: |
65 | | -You can develop your own style by using the asciidoctor facilities. Therefore create your own theme in the path `theme/custom-theme.yml` and also push it to the wiki git repo. |
66 | | - |
67 | | -== Usage |
68 | | -To start the generation manually you need to clone the wiki with the documentation to generate as described above. Then open a command shell in the cloned project and call: |
69 | | -[source,cmd] |
70 | | --------- |
71 | | -mvn clean package |
72 | | --------- |
73 | | - |
74 | | -Then you will find the result in `target/generated-docs/`. |
75 | | - |
76 | | -If you want to deploy your documentation to maven central run: |
77 | | -[source,cmd] |
78 | | --------- |
79 | | -mvn deploy -Dgpg.keyname=<yourkeyname> -Poss |
80 | | --------- |
81 | | - |
82 | | -It is a common practice to store all the images used in a folder called "images", so docgen search in "images" as default. If you want to specify other directory or multiple, it can be done as follows: |
83 | | - |
84 | | -[source,cmd] |
85 | | --------- |
86 | | -mvn clean package -Doutput.format=pdf -Ddocgen.images.dir=images1,images2,...,imagesn |
87 | | --------- |
88 | | - |
89 | | -== Guidelines |
90 | | -In order to make DocGen work properly please follow these guidelines: |
91 | | - |
92 | | -* Maintain the documentation as collection of wiki pages. |
93 | | -* For the wiki usage link (important) pages in the sidebar for navigation. |
94 | | -* Use http://www.methods.co.nz/asciidoc/[AsciiDoc] for all wiki pages. This is not the default on github. Always switch `Edit mode` to `AsciiDoc` when creating new wiki pages. |
95 | | -* For help on the syntax consult the http://asciidoctor.org/docs/asciidoc-writers-guide/[writers guide] and the https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[quick reference]. |
96 | | -* Start every page with the following AsciiDoc header: |
97 | | -+ |
98 | | -[source,asciidoc] |
99 | | --------- |
100 | | -:toc: macro |
101 | | -toc::[] |
102 | | -:idprefix: |
103 | | -:idseparator: - |
104 | | --------- |
105 | | -+ |
106 | | -* In order to make internal links work both in wiki as well as in generated documentation (PDF, ePub, HTML) you need to stick to this rules: |
107 | | -** Do not use special characters (dot, ampersand, etc.) in section titles (use plain text e.g. "My Section") |
108 | | -** If you link to a section, you simply use the section title in lower case with hyphens instead of spaces (e.g. "my-section"). Within the same wiki page you use `xref` (e.g. `xref :my-section[link title]`) and between wiki pages you use `link` (e.g. `link :guide-my-topic#my-section[link title]`). |
109 | | -** In case you want to reference the top-level section of a wiki page you need to use +link+ without a section reference (e.g. `link :guide-my-topic[link title]`) and NOT `xref` even if you place the link within the same wiki page. |
110 | | -** From wiki pages included in the generated documentation only use `link:` to other wiki pages that will also be part of the generated documentation. Otherwise you would produce dead links. |
111 | | -* For editing larger files and offline work we recommend to clone the wiki with git and use an xref:asciidoc-tools[AsciiDoc editor tool]. |
112 | | -* You need to ensure that the files use UTF-8 as encoding. |
113 | | -* To include images you need to follow this rules: |
114 | | -** The best choice for high quality rendering is `SVG`. As the wiki does not create mimetypes you have to |
115 | | -put the image on the https://github.com/devonfw/devonfw.github.io/[github pages]. |
116 | | -** You have to set the size so it gets properly rendered in the PDF. The width value to make it fit properly on the PDF page is `450`: |
117 | | -+ |
118 | | -[source,asciidoc] |
119 | | --------- |
120 | | -.Image Title |
121 | | -image::http://devonfw.github.io/devon4j/images/MyImage.svg["alt-text", width="450", link="http://devonfw.github.io/devon4j/images/MyImage.svg"] |
122 | | --------- |
123 | | -* For devonfw the wiki pages belong to categories that are also reflected by a naming convention: |
124 | | -** `coding-*` is used for pages about general aspects to development and writing code. |
125 | | -** `guide-*` is used for pages that act as a guide to a specific topic. It describes what to do and how to do it for that topic from the perspective of a developer. |
126 | | -** `alternative-*` is used for pages that are not part of the suggested standard but are commonly used or popular alternatives to a proposed standard solution. Such page explains how to use such an alternative solution. |
127 | | -** `architecture` is reserved for the architecture documentation. |
128 | | -** `introduction-*` is used for pages that are part of the introduction into the documentation (motivation and general goals). |
129 | | -** `devon-*` is used for pages that are about the devonfw itself and will not be part of the official documentation. |
130 | | -** `tutorial-*` is used for pages that are part of the tutorials. |
131 | | - |
132 | | -== Migration |
133 | | -If you migrate from devon-docgen 3.x to 4.x generating PDFs, you now have to add `-Doutput.format=pdf` to your maven build command. Similarly, for html generation it would be `-Doutput.format=html`. |
134 | | - |
135 | | -== Tooling |
136 | | -Our DocGen tool is technically based on the following tools: |
137 | | - |
138 | | -* http://maven.apache.org[maven] |
139 | | -* http://asciidoctor.org[asciidoctor] |
140 | | -** via http://asciidoctor.org/docs/asciidoctor-maven-plugin[asciidoctor-maven-plugin] |
141 | | -* http://www.docbook.org[docbook] |
142 | | -** via http://docbkx-tools.sourceforge.net/docbkx-maven-plugin/plugin-info.html[docbkx-maven-plugin] |
143 | | -** using http://docbook.sourceforge.net/release/xsl/current[docbook XSL distribution] |
144 | | -* http://ant.apache.org[ant] |
145 | | -** via http://maven.apache.org/plugins/maven-antrun-plugin[maven-antrun-plugin] |
146 | | - |
147 | | -This setup was inspired by https://github.com/spring-projects/spring-boot/tree/master/spring-boot-docs/[spring-boot-docs] and improved for link processing, etc. |
148 | | -Feel free to get inspired here or copy the entire solution if you like it. |
149 | | -Thanks to all authors of the actual tools and to spring-boot for making this great DocGen happen. |
| 9 | +== Documentation |
150 | 10 |
|
151 | | -== AsciiDoc Tools |
152 | | -You can checkout a github wiki as a git repository and edit it with an editor of your choice. For this we recommend the following tools: |
| 11 | +* link:documentation/features.asciidoc[Features] |
| 12 | +* link:documentation/usage.asciidoc[Usage] |
| 13 | +* link:documentation/guidelines.asciidoc[Guidelines] |
| 14 | +* link:documentation/migration.asciidoc[Migration] |
| 15 | +* link:documentation/tools.asciidoc[AsciiDoc Tools] |
| 16 | +* link:documentation/credits.asciidoc[Credits] |
153 | 17 |
|
154 | | -* http://www.asciidocfx.com/[AsciiDocFx] |
155 | | -* https://plugins.jetbrains.com/plugin/7391-asciidoc[AsciiDoc for IntelliJ] |
156 | | -* https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode[AsciiDoc for VS Code] |
157 | | -* https://addons.mozilla.org/fr/firefox/addon/asciidoctorjs-live-preview/[Asciidoc for Firefox] |
158 | | -* https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia[Asciidoc for Chrome] |
159 | | -* https://atom.io/packages/asciidoc-preview[Asciidoc preview for Atom] and https://atom.io/packages/language-asciidoc[Asciidoc language for Atom] |
160 | | -* https://github.com/asciidoctor/brackets-asciidoc-preview[Asciidoc for Brackets] |
0 commit comments