Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/fpapon/apache-manual


https://github.com/fpapon/apache-manual

Last synced: 5 days ago
JSON representation

Awesome Lists containing this project

README

        

# Apache Manual

Apache Manual is a template project to generate manual documentation of Apache projects.

The goal of this project is to generate the documentation in **html** and **pdf** format using a theme related to the
[Apache Software Foundation](https://apache.org) website.

This project use the [asciidoctor-maven-plugin](https://github.com/asciidoctor/asciidoctor-maven-plugin).

## Structure

The asciidoc manual example pages are located under `src/manual/asciidoc`.

The example pages is a copy of some of pages of the [Apache Software Foundation](https://apache.org) website.
This pages is used only for the illustration of the usage of this project.

## Generation

### HTML

The custom Apache CSS is located under `src/manual/asciidoc/style/apache.css`.

The images used in the documentation is in the `ìmages` folder.

You have to declare the plugin in the pom.xml of your manual maven module:

```

html

process-resources


org.asciidoctor
asciidoctor-maven-plugin
1.5.6


output-html
generate-resources

process-asciidoc


html5
article


true
style/apache.css
images





src/manual/asciidoc
target/generated-html/${project.version}
true
true
src/manual/asciidoc/images



```

You can change some configuration parameters like:

***sourceDirectory***

main folder of the asciidoc files.

***outputDirectory***

folder where html files are generated.

For others configuration, you can have a look on the [asciidoctor-maven-plugin](https://github.com/asciidoctor/asciidoctor-maven-plugin).

This example use an `index.adoc` main file and a table of content at the left sidebar.

To launch the html buidl, just run the maven command using the html profile:

```
mvn clean -Phtml
```

### PDF

The custom Apache theme is located under `src/manual/theme/apache-theme.yml`.

The fonts used is located under `src/manual/theme/fonts`

The images used in the documentation is in the `ìmages` folder.

You have to declare the plugin in the `pom.xml` of your manual maven module:

```

pdf

process-resources


org.asciidoctor
asciidoctor-maven-plugin
1.5.6


org.asciidoctor
asciidoctorj-pdf
1.5.0-alpha.16



src/manual/asciidoc
target/generated-pdf/${project.version}
true
true
pdf

${project.version}
${project.basedir}/src/manual/theme
apache
${project.basedir}/src/manual/theme/fonts
images
font
true


-
true




generate-pdf-doc
generate-resources

process-asciidoc







```

You can change some configuration parameters like:

***sourceDirectory***

main folder of the asciidoc files.

***outputDirectory***

folder where pdf files are generated.

For others configuration, you can have a look on the [asciidoctor-maven-plugin](https://github.com/asciidoctor/asciidoctor-maven-plugin).

To launch the pdf build, just run the maven command using the *pdf* profile:

```
mvn clean -Ppdf
```

The aggregate generated file is `index.pdf` located in the *outputDirectory*.

## Contribute

If you want to help you are welcome to push some PR or to contact me ;)

Copyright © 2018 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache and the Apache feather logo are trademarks of The Apache Software Foundation.