Skip to content
Permalink
Browse files

i12 Improved demo on site

  • Loading branch information...
Pingvin235 committed Oct 1, 2019
1 parent 6115416 commit fd0581305839a5927112a0e5b6fd790516155573
@@ -18,27 +18,34 @@ Ideally fits for continuous delivery approach, when documentation is considered
stored, handled together with other sources. Documentation is automatically built using GitLab CI and published,
you may see the result link:https://bgerp.ru/doc/3.0/manual/[here].

The key features:
=== The key features
[square]
* Delivered as a single artifact in Maven repository for simple integration in existing build processes.
* Building documentation out of many files structure with common ToC.
* Built-in search over EN, RU and DE using link:https://lunrjs.com/[LunrJS].
* Handling of dependent resources (images, files).
* Original approach for organization of files structure.
* Delivered as a single Java artifact in Maven repository for simple integration in existing build processes.
* Building documentation out of many files structured in original way with ToC.
* Preserving structure, preview of documentation is <<src/doc/demo.adoc#, available>> in GitLab and GitHub.
* Produce embedded JS search over EN, RU and DE using link:https://lunrjs.com/[LunrJS].
* Internal references checking, no more broken links.
* Extension for referencing of JavaDoc by class name.
* Some CSS adjustments.
* Preview of documentation is link:demo/src/index.adoc[available] in GitLab and GitHub.
* CSS enhancements.

== HOWTO
The link:demo/src[demo] set shows the key ideas using examples and may be used as a reference or a start set.

Clone the repository, after execute in the directory:
== Logic
[square]
* As parameter generator takes input and output directories.
* Input directory may be taken directly from project or checked out from version control to outside like `target`.
First way is easier, in the second one may be combined doc sources out of many GIT projects.
* In the input directory mast be placed `index.adoc` with table of contents.
* In the input directory may be placed `pzdcdoc.xml` file with different parameters.
AsciiDoctor attributes from the file are included in all of converted `.adoc` files.
* The generator goes through all the files in input dir and converting all with extension `.adoc` them to `.html`.
** Directory starting from `.` are skipped.
** Includes have to be named `.adocf` to avoid converting.
** Resources (files, images) are recommened to place in `_res` subdirectory near of referencing `.adoc` file.
* All the used references between `.adoc` are relative and automatically converted to HTML.

== How to test
Clone the GIT repository, after execute in the directory:
[source]
----
gradlew buildDemoDoc
----
That will build result to target/doc.

Use "demo build" configuration from link:build.gradle[] as a sample for your own project.

That will build result to `target/doc-out`, these files may be published on HTTP server.
@@ -1,4 +1,4 @@
/*
/*
Local publishing:
gradlew publishToMavenLocal
To Sonatype:
@@ -12,15 +12,18 @@ apply plugin: 'eclipse'
apply plugin: 'idea'

repositories {
mavenLocal()
mavenCentral()
mavenLocal()
mavenCentral()
}

buildDir = 'target'
version = '1.3'
sourceCompatibility = 1.8
targetCompatibility = 1.8

ext.admin = hasProperty('sonatypeUsername')
ext.docSrcDir = "${buildDir}/doc-src"

eclipse {
classpath {
// enable here source download if needed
@@ -34,12 +37,12 @@ idea {
}

configurations {
all {
transitive = false
all {
transitive = false
}
// for demo build
pzdcdoc {
transitive = true
transitive = true
}
}

@@ -58,7 +61,7 @@ dependencies {
compile group: 'com.fasterxml.jackson.core', name: 'jackson-core', version: '2.10.0.pr3'
compile group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.10.0.pr3'
compile group: 'com.fasterxml.jackson.core', name: 'jackson-annotations', version: '2.10.0.pr3'
// for demo build
pzdcdoc group: 'org.pzdcdoc', name: 'pzdcdoc', version: "${project.version}"
}
@@ -71,11 +74,14 @@ tasks.withType(Javadoc) {
options.encoding = 'UTF-8'
}

// demo build
task buildDemoDoc(type:JavaExec) {
classpath = configurations.pzdcdoc
main = 'org.pzdcdoc.DocGenerator'
args 'NOTUSED', 'demo/src', 'target/doc'
task checkoutDemoDoc(type: Exec, dependsOn: clean) {
commandLine 'git', 'clone', 'https://github.com/pzdcdoc/pzdcdoc.git', docSrcDir, '--depth', '1', '--branch', 'master'
}

task buildDemoDoc(type:JavaExec, dependsOn: ['checkoutDemoDoc']) {
classpath = configurations.pzdcdoc
main = 'org.pzdcdoc.DocGenerator'
args 'NOTUSED', docSrcDir, 'target/doc-out'
}

task sourceJar(type: Jar) {
@@ -88,8 +94,6 @@ task javadocJar(type: Jar, dependsOn: javadoc) {
from javadoc.destinationDir
}

ext.admin = hasProperty('sonatypeUsername')

artifacts {
archives sourceJar
archives javadocJar
@@ -106,7 +110,7 @@ signing {
publishing {
publications {
mavenJava(MavenPublication) {
groupId 'org.pzdcdoc'
groupId 'org.pzdcdoc'
artifactId 'pzdcdoc'
version "${project.version}"

@@ -149,15 +153,15 @@ publishing {
}
}

repositories {
maven {
url "https://oss.sonatype.org/service/local/staging/deploy/maven2"
credentials {
username findProperty('sonatypeUsername')
password findProperty('sonatypePassword')
}
}
}
repositories {
maven {
url "https://oss.sonatype.org/service/local/staging/deploy/maven2"
credentials {
username findProperty('sonatypeUsername')
password findProperty('sonatypePassword')
}
}
}
}

def customizePom(pom) {

This file was deleted.

@@ -0,0 +1,9 @@
= Demo ToC
:nofooter:

* <<README.adoc#, README>>
* <<{doc-path}/demo.adoc#, Demo AsciiDoctor>>
* Modules
** <<{doc-path}/module/index.adoc#, Module>>
* <<{doc-path}/changes.adoc#, Last changes>>
@@ -3,6 +3,8 @@
<pzdcdoc>
<!-- these attributes applied to each of processed files, may be overvritten inside -->
<attributes>
<doc-path>src/doc</doc-path>

<favicon>https://bgerp.ru/img/favicon.png</favicon>
<pzdc-javadoc>http://www.bgcrm.ru/doc/3.0/javadoc/</pzdc-javadoc>
<!-- sample of labels customization
File renamed without changes.
File renamed without changes.
@@ -5,4 +5,4 @@ Last changes in the documentation.

== Log of changes
[square]
* <<about.adoc#, 25.04.2019>> Added the chapter "About".
* <<demo.adoc#, 01.10.2019>> Added the chapter "Demo".
@@ -1,4 +1,4 @@
= About
= Demo AsciiDoctor syntax
:toc:

Full reference of AsciiDoctor syntax is available here: https://asciidoctor.org/docs/user-manual
File renamed without changes.
File renamed without changes.
@@ -1,4 +1,5 @@
= TODO

== This article is not complete
WARNING: This link has to be replaced to the correct one. Please, inform developers.

0 comments on commit fd05813

Please sign in to comment.
You can’t perform that action at this time.