From f1e5df7236aac5e1c8ed364050deb8d608b9f654 Mon Sep 17 00:00:00 2001 From: Michael Vorburger Date: Wed, 12 Jul 2017 12:55:12 +0530 Subject: [PATCH] Remove outdated src/site documentation see https://lists.opendaylight.org/pipermail/odlparent-dev/2017-July/001218.html Change-Id: Ie1580e11fa449ed38864960c868c4930f847e291 Signed-off-by: Michael Vorburger --- odlparent-lite/src/site/site.xml | 21 -- src/site/asciidoc/asciidoc-in-site.adoc | 303 ------------------------ src/site/markdown/maven-site.md | 193 --------------- src/site/site.xml | 10 - 4 files changed, 527 deletions(-) delete mode 100644 odlparent-lite/src/site/site.xml delete mode 100644 src/site/asciidoc/asciidoc-in-site.adoc delete mode 100644 src/site/markdown/maven-site.md delete mode 100644 src/site/site.xml diff --git a/odlparent-lite/src/site/site.xml b/odlparent-lite/src/site/site.xml deleted file mode 100644 index e8728c5f6..000000000 --- a/odlparent-lite/src/site/site.xml +++ /dev/null @@ -1,21 +0,0 @@ - - - - OpenDaylight - https://www.opendaylight.org/sites/all/themes/odl2/logo.png - https://www.opendaylight.org/ - 457 - - - - - - - - - - org.apache.maven.skins - maven-fluido-skin - 1.4 - - diff --git a/src/site/asciidoc/asciidoc-in-site.adoc b/src/site/asciidoc/asciidoc-in-site.adoc deleted file mode 100644 index 800783ff3..000000000 --- a/src/site/asciidoc/asciidoc-in-site.adoc +++ /dev/null @@ -1,303 +0,0 @@ -= Using AsciiDoc in Maven Site -Tony Tkacik - -AsciiDoc became de-facto standard documentation language for OpenDaylight, -so if you are using `odlparent-lite`, `odlparent` or any parent POM derived from -these, ODLParent-based Maven Site support AsciiDoc with additional -following features: - -- <> -- <> - -== Overview - -AsciiDoc belongs to the family of -http://en.wikipedia.org/wiki/Lightweight_markup_language[lightweight markup languages], -the most renowned of which is http://daringfireball.net/projects/markdown/[Markdown]. - -AsciiDoc stands out from this group because it supports all the structural elements -necessary for drafting articles, technical manuals, books, presentations and prose. -In fact, it's capable of meeting even the most advanced publishing requirements -and technical semantics. - - - -http://asciidoctor.org[Asciidoctor.org] ,which we are using, provides -http://asciidoctor.org/docs/asciidoc-writers-guide/[excellent guide how to write in AsciiDoc]. - - -[[code-highlighting]] -== Code Highlighting - -Asciidoctor.org integration provides support for code examples and highlighting -syntax in code blocks. - -.Anatomy of a source code block -[source, asciidoc] -.... -.Optional caption // <1> -[source,language] // <2> <3> ----- -Source code // <4> ----- -.... -<1> Optional caption of code listing -<2> `source` keyword is required to mark block as source code listing -<3> Optional specifier of language -<4> Actual source code. - -Support of code highlighting depends on used highlighter backend, but most -common languages are usually supported. Usually following language identifiers -are supported : -`java`, `scala`, `groovy`, `c`, `ruby`, `html`, `xml`, `json`, `javascript`, -`yang` (not all highlighters support it). - - -See http://asciidoctor.org/docs/asciidoc-writers-guide/#listing-and-source-code-blocks[Asciidoc Writer's Guide] -for more examples and additional documentation on source code. - -[[diagram-rendering]] -== Diagram Rendering - -Diagrams are vital part of software documentation, but it is hard to standardize -on format and standard image formats are cumbersome to maintain and track -in changing environment of software development. Textual form of diagrams -in AsciiDoc makes easier to separate layout and rendering from content and it -is more natural to be version tracked. - -Diagram rendering is provided by `asciidoctor-diagram` extension to Asciidoctor, -which allows you to inline / create diagrams in text and the extension takes -care of rendering them into images. - -Most usable family of diagrams is probably `plantuml` family of diagrams, which -allows you textually specify UML models and extension takes care of rendering -images. - -NOTE: Although `asciidoctor-diagram` provides various types of diagram and -backends, it is necessary to have these backends installed in order for them -to work. If backend is not present, `asciidoctor-diagram` will display source -of diagram instead. - -=== Creating diagram - -A diagram is written inside a literal block, which can accept several attributes. - -.Anatomy of a diagram -[source, asciidoc] ----- -[block-name, generated-file-name, generated-file-extension] // <1> <2> <3> -.... // <4> -ditaa, PlantUML or other supported diagram syntax -.... ----- -<1> The first position in the attribute list assigns the block's name. -<2> The second, optional position assigns a file name (i.e. `target`) to the generated diagram. If a target is not specified an auto-generated name will be used. -<3> The third, optional position assigns a file extension (i.e. `format`) to the generated diagram. -<4> Place the attribute list directly on top of the delimited literal block (`....`). Diagram block names can also be assigned to open blocks (`--`). - -The following block names and output formats are available: - -`plantuml`:: -Supports `png`, `svg` and `txt` output formats. - -`graphviz`:: -Supports `png` and `svg` output formats. - -`ditaa`:: -Supports the `png` output format. - -=== PlantUML diagrams - -In order to use and render http://plantuml.com/[PlantUML] diagrams you need -http://www.graphviz.org/[Graphviz] installed and be familiar with http://plantuml.com/[PlantUML syntax]. -Inside Asciidoc block you should not use `@startuml` and `@enduml` tags. - -.Source -[source, asciidoc] ----- -.Example Diagram // <1> -[plantuml, odlparent-overview, png] // <2> <3> <4> -.... -component "odlparent-lite" as odlparent.lite // <5> -component "odlparent" as odlparent -odlparent -> odlparent.lite -.... ----- -<1> Title of diagram -<2> Type of diagram, in this case it is PlantUML diagram -<3> Name of generated file, in this case it is `odlparent-lite` -<4> Type of generated file -<5> PlantUML source of diagram. - - -This Asciidoc source would result in following: - -.Example Diagram -[plantuml, odlparent-overview, png] -.... -component "odlparent-lite" as odlparent.lite -component "odlparent" as odlparent -odlparent -> odlparent.lite -.... - - -==== Types of Diagrams - -PlantUML provides support for following types of diagram: - -* <> -* <> -* <> -* <> -* <> - -[[component-diagram]] -==== Component diagram - -.Example source -[source, asciidoc] ----- -.Example component diagram -[plantuml, component-overview, png] -.... -() HTTP // <1> -() "Servlet API" as servlet.api // <2> - -component "HTTP Server" as server // <3> -component "HTTP Client" as client -component "Java Application" as app - - -client ..> HTTP : use // <4> -HTTP - server // <5> -server - servlet.api - -app ..> servlet.api : use -.... ----- -<1> Definition of interface `HTTP` -<2> Definition of interface `Servlet API` with alias `servlet.api` -<3> Definition of component `HTTP Server` with alias `server` -<4> Definition of uses relationship : dashed link between `client` and `HTTP` with `use` label -<5> `HTTP Server` provides `HTTP` API. -This source would result into following diagram: - -.Example component diagram -[plantuml, component-overview, png] -.... -() HTTP -() "Servlet API" as servlet.api - -component "HTTP Server" as server -component "HTTP Client" as client -component "Java Application" as app - - -client ..> HTTP : use -HTTP - server -server - servlet.api - -app ..> servlet.api : use -.... - - -For more documentation and examples of component diagrams see -http://plantuml.com/component.html[PlantUML documentation on Component Diagram]. - -[[class-diagram]] -==== Class diagram - -.Example source -[source, asciidoc] ----- -.Class Diagram -[plantuml,abstract-list-example, png] -.... - -class Object { // <1> - + toString() : String -} -interface Iterable { // <2> - + hasNext() : boolean - + next() : T -} - -Object <|-- AbstractList // <3> -Iterable <|.. AbstractList // <4> -.... ----- -<1> Explicit definition of class `Object` -<2> Explicit definition of generic interface `Iterable` -<3> Implicit definition of class `AbstractList`, which extends `Object` -<4> `AbstractList` implements `Iterable` - -The source will result into following diagram: - -.Class Diagram -[plantuml,abstract-list-example, png] -.... - -class Object { - + toString() : String -} -interface Iterable { - + hasNext() : boolean - + next() : T -} - -class AbstractList { - -} - -Object <|-- AbstractList -Iterable <|.. AbstractList -.... - -For more documentation and examples of class diagrams see -http://plantuml.com/classes.html[documentation of Component Diagram]. - -[[sequence-diagram]] -==== Sequence diagram - -.Example source -[source, asciidoc] ----- -[plantuml, sequence-example, png] -.... -Alice -> Bob: Authentication Request -Bob --> Alice: Authentication Response - -Alice -> Bob: Another authentication Request -Alice <-- Bob: another authentication Response -.... ----- - -The source will result into following diagram: - -.Sequence diagram example -[plantuml, sequence-example, png] -.... -Alice -> Bob: Authentication Request -Bob --> Alice: Authentication Response - -Alice -> Bob: Another authentication Request -Alice <-- Bob: another authentication Response -.... - - -For more documentation and examples of sequence diagrams see -http://plantuml.com/sequence.html[documentation of Sequence Diagram]. - - -[[activity-diagram]] -==== Activity diagram - -For more documentation and examples of activity diagrams see -http://plantuml.com/activity.html[documentation of Activity Diagram] -or http://plantuml.com/activity2.html[different syntax for Activity Diagram]. - -[[state-diagram]] -==== State diagram - -For more documentation and examples of state diagrams see -http://plantuml.com/state.html[documentation of State Diagram]. diff --git a/src/site/markdown/maven-site.md b/src/site/markdown/maven-site.md deleted file mode 100644 index 9fa5862fe..000000000 --- a/src/site/markdown/maven-site.md +++ /dev/null @@ -1,193 +0,0 @@ -Maven Site is a handy tool for auto-generating a website containing site -details for your project based on information scanned from project pom files. -It can also be used to auto-generate coverage reports and Javadoc pages. This -page will describe how to generate a Maven site for your ODL project. - -* [Enable Maven Site generation](#enable_site) -* [Fix site urls](#fix_site_urls) -* [Customize project site](#customize_site) -* [Aggregating Java apidocs](#aggregate_apidocs) -* [Local Site Generation](#local_site_gen) - -## Enabling Maven Site generation - -The odlparent project provides most of the necessary configuration already to -generate a Maven site for all ODL projects but the site generation is disabled -by default. In order to enable site generation you will need to create a file -called "deploy-site.xml" in the root of your project repo. This file's -existance will cause the Maven build as well as ODL Jenkins system to start -generating and deploying the site to Nexus. - -Below is an example configuration you can copy to create the deploy-site.xml -this file is not too complicated and the only thing you need to change is to -ensure that the \ is configured to use your project's namespace. - - - - - - 4.0.0 - - org.opendaylight.PROJECT - deploy-site - 1.0.0-SNAPSHOT - pom - - - latest - dav:https://nexus.opendaylight.org/content/sites/site/${project.groupId}/${stream}/ - - - - - - org.apache.maven.wagon - wagon-webdav-jackrabbit - 2.9 - - - - - - org.apache.maven.plugins - maven-site-plugin - 3.4 - - ${project.build.directory}/staged-site - - - - - - - - opendaylight-site - ${nexus.site.url} - - - - -Note that the above file is a dummy file who's only purpose is to push a -staged-site to Nexus as well as being the trigger for odlparent to activate -site generation for your project. - -## Fix Maven Site URLs - -The maven-site-plugin assumes projects are configured in a certain Maven way -which unfortunately ODL is not configured as such. This causes the site plugin -to generate invalid URLs to all project modules. The workaround for this is to -pass both a url and a distribution.site.url for every single module in your -Maven project. The following template should be placed into all modules in an -ODL project with the exception of the root pom (this will be explained below the -example). - - - ${odl.site.url}/${project.groupId}/${stream}/${project.artifactId}/ - - - - opendaylight-site - ${nexus.site.url}/${project.artifactId}/ - - - -**Note:** For the project root pom.xml remove the final path -"${project.artifactId}" from both URLs. This is so that the root project -can represent the root index page for your project when the Maven Site is -deployed. - -## Customize project site - -In the root pom of your project you can create customized site including -creating your own project Documentation via markdown (or other formats) -using the maven-site-plugin. Please refer to Maven Site documentation for -how to customize your site. - -The general documentation can be found here -https://maven.apache.org/plugins/maven-site-plugin/ - -The following pages are particularly useful regarding creating your site -content: - - * https://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html - * https://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html - -## Aggregating Java apidocs - -Javadoc is generated automatically for each bundle however to aggregate them -all into a single convenient url we need to ensure that the root pom has a -profile to activate it. The following should be copied into the profiles -section of the project root pom. - - - - - maven-site - - - ${user.dir}/deploy-site.xml - - - - - - - org.apache.maven.plugins - maven-javadoc-plugin - false - - - aggregate - - aggregate - - package - - - - - - - - -Also once you have the configuration to generate apidocs you will also want to -create a site.xml to add a menu item in Maven Sites linking back to the apidocs. - -Create the file src/site/site.xml in the root of your project with the following -contents: - - - - - - - - - - -Replace PROJECT with the name of your project for example "odlparent" or -"controller" etc... - -## Local Site Generation - -To test Maven Site Generation locally you can run a build and then deploy a -staging site locally and view it with your webbrowser. - - mvn clean install - mvn site:deploy -Dstream=boron - firefox target/staged-site/index.html diff --git a/src/site/site.xml b/src/site/site.xml deleted file mode 100644 index 16eadcbeb..000000000 --- a/src/site/site.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - - - -- 2.36.6