Documented: OFBizDocumentationSystem migration to Asciidoc and Review (OFBIZ-11364)
Rewrite the document, add a part in documentation guidline. Add a include for OFBizDocumentationSystem document in user manual and developer-manual.
This commit is contained in:
@@ -0,0 +1,89 @@
|
||||
////
|
||||
Licensed to the Apache Software Foundation (ASF) under one
|
||||
or more contributor license agreements. See the NOTICE file
|
||||
distributed with this work for additional information
|
||||
regarding copyright ownership. The ASF licenses this file
|
||||
to you under the Apache License, Version 2.0 (the
|
||||
"License"); you may not use this file except in compliance
|
||||
with the License. You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing,
|
||||
software distributed under the License is distributed on an
|
||||
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
||||
KIND, either express or implied. See the License for the
|
||||
specific language governing permissions and limitations
|
||||
under the License.
|
||||
////
|
||||
= The Apache OFBiz documentation system
|
||||
|
||||
== Overview
|
||||
there are two supports for OFbiz documentation, the https://cwiki.apache.org/confluence/display/OFBENDUSER/OFBiz+End+User+Docs+Home[wiki]
|
||||
and some mains documents (in pdf and html format)
|
||||
|
||||
* user-manual
|
||||
* developer-manual
|
||||
* documentation_guidelines
|
||||
* README
|
||||
|
||||
=== Asciidoc
|
||||
The OFBiz documents are generated from a number of Asciidoc files. In general the files are stored on each component
|
||||
in the 'src/docs/asciidoc' directories. +
|
||||
The general main documents include all files from component.
|
||||
|
||||
The manuals and guidelines documents are located in docs/asciidoc directories, and REAME.adoc is in root directory.
|
||||
|
||||
Help link in the OFBiz user interface, are link to the user-manual generated by buildbot process from Apache OFBiz community.
|
||||
It’s possible to change a property in OFBiz to have link to your own generation.
|
||||
|
||||
For details about asciidoc rules used in Apache OFBiz have a look to link:documentation_guidelines.html[Documentation Guidelines]
|
||||
|
||||
==== Application components
|
||||
All main files of each component are included in user-manual.adoc
|
||||
|
||||
==== Framework components
|
||||
All main files of each component are included in developer-manual.adoc except for webtools which is included in user-manual
|
||||
|
||||
==== Plugins
|
||||
For the main files of the plugin components, there are two ways to read them.
|
||||
|
||||
On the one hand, the plugin documentation generation process generates one document per plugin, so that you can see
|
||||
the list of documents in the link:../../pluginsdoc/html5[pluginsdoc directory] and thus read each of them;
|
||||
|
||||
On the other hand, each plugin master file is included in the plugin chapter of the user manual or developer manual,
|
||||
depending on whether the plugin is "technical" or "functional".
|
||||
|
||||
=== Wiki
|
||||
Wiki is the second way to contribute to the documentation.
|
||||
Detail on how to https://cwiki.apache.org/confluence/display/OFBENDUSER/Help+for+providing+help+content[Help for providing help content]
|
||||
is on the wiki icon:smile-o[]
|
||||
|
||||
Most of wiki page has been or will be migrated to the asciidoc pages, but, as wiki is more easier to be update
|
||||
(update existing page or create new one) the two system will continue to exist and live.
|
||||
|
||||
|
||||
== Contributing a new help screen, a few steps.
|
||||
link:documentation_guidelines.html[Documentation Guidelines] is the first doc to read to be able to contribute to documentation
|
||||
and/or help.
|
||||
|
||||
If you are looking for asciidoc files format examples, please look at the following files:
|
||||
|
||||
. An example for a chapter of a component at: applications/humanres/src/docs/asccidoc/_include/hr-intro.adoc
|
||||
. An example of a help screen: applications/humanres/src/docs/asccidoc/_include/HELP-hr-main.adoc
|
||||
|
||||
=== Screens
|
||||
If you would like to create a new help for a certain screen, you need to do the following:
|
||||
|
||||
. Write documentation in a functional point of view and in a process perspective.
|
||||
. Each title (in all level) generate in html an anchor, so starting point of the help should be a title.
|
||||
. Take the anchor generated (something like _the_title , with only lowercase), for example by looking in the html file generated.
|
||||
. In the screen add a `<set field` for `helpAnchor` with anchor generated as value.
|
||||
|
||||
== Internationalization of the help system
|
||||
Currently documentation is only in English (except for 3 or 4 files, not included).
|
||||
|
||||
In near future, there will be a solution to be able to have documentation/help in multiple languages,
|
||||
a https://issues.apache.org/jira/browse/OFBIZ-12030[jira (OFBIZ-12030)] is open of that.
|
||||
|
||||
The switching between locale will be completely automatic (depending on OFBiz user local)
|
||||
@@ -190,6 +190,8 @@ Continuing the example, the FindInvoices screen contains many details including
|
||||
two forms. One form is for entering invoice search fields and the other form
|
||||
displays search results.
|
||||
|
||||
include::_include/OFBizDocumentationSystem.adoc[leveloffset=+2]
|
||||
|
||||
== Web Framework
|
||||
|
||||
include::../../framework/webapp/src/docs/asciidoc/webapp.adoc[leveloffset=+1]
|
||||
|
||||
@@ -51,7 +51,7 @@ how we are organised.
|
||||
|
||||
=== Document configuration
|
||||
|
||||
Documents that will be published as standalone guides (e.g. developer manual, user manual) should contain common configuration
|
||||
Documents that will be published as standalone guides (e.g. link:developer-manual.adoc[developer manual], link:user-manual.adoc[user manual]) should contain common configuration
|
||||
so that the output will be generated in exactly the same way for all documents.
|
||||
|
||||
[NOTE]
|
||||
@@ -123,6 +123,34 @@ under the License.
|
||||
////
|
||||
----
|
||||
|
||||
=== file organization
|
||||
There are one main file per application (located in the 'src/docs/asciidoc' directory), which include some other files
|
||||
located in 'src/docs/asciidoc/_include'.
|
||||
|
||||
.For each component, there are these directories:
|
||||
====
|
||||
src
|
||||
|- docs
|
||||
|- asciidoc
|
||||
|- _include
|
||||
|- images
|
||||
|- ${componentName}
|
||||
====
|
||||
|
||||
So, for include file use
|
||||
|
||||
include::_include/xxxxxxx
|
||||
|
||||
and for image, it's necessary to add on top of main file
|
||||
|
||||
:imagesdir: ./images/${compnentName}
|
||||
|
||||
and so include them with
|
||||
|
||||
image::/xxxxxxx
|
||||
|
||||
During generating process images are copied on the root asciidoc/images directory
|
||||
|
||||
=== File name conventions
|
||||
|
||||
We will be implementing a consistent naming convention for the documentation content files.
|
||||
@@ -137,7 +165,6 @@ so the naming format will be ([shortname]-intro, [shortname]-glossary, [shortnam
|
||||
[shortname]-security etc.)
|
||||
|
||||
.For Human Resources this will be as follows:
|
||||
[example]
|
||||
====
|
||||
humanres.adoc
|
||||
|- hr-intro.adoc
|
||||
@@ -481,10 +508,15 @@ SELECT * FROM FOO;
|
||||
== Importing files or file includes
|
||||
|
||||
You can import files via the include macro.
|
||||
This also works for source code includes.
|
||||
To use ---- in your listing use the [listing] style before that.
|
||||
This also works for source code includes. +
|
||||
It's possible to use [listing] ---- before include to have the correct style. +
|
||||
The following example imports a file formatted as Java source code.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
include::resource/source.java[]
|
||||
----
|
||||
|
||||
[source,java]
|
||||
----
|
||||
include::resource/source.java[]
|
||||
|
||||
@@ -136,6 +136,8 @@ to the core applications in design and structure, but are not shipped with
|
||||
OFBiz by default. Thus to install a plugin a user must add it to the framework
|
||||
first.
|
||||
|
||||
include::_include/OFBizDocumentationSystem.adoc[leveloffset=+2]
|
||||
|
||||
include::../../README.adoc[tags=quickstart]
|
||||
|
||||
include::../../applications/commonext/src/docs/asciidoc/ofbiz-setup.adoc[leveloffset=+1]
|
||||
|
||||
Reference in New Issue
Block a user