This is an automated email from the ASF dual-hosted git repository.
holivier pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/ofbiz-framework.git
The following commit(s) were added to refs/heads/trunk by this push:
new ac6964e Documented: OFBizDocumentationSystem migration to Asciidoc
and Review (OFBIZ-11364)
ac6964e is described below
commit ac6964e8eba64c8a84a5954e2e2fead0e434fbb0
Author: holivier <[email protected]>
AuthorDate: Sat Nov 14 16:55:31 2020 +0100
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.
---
.../_include/OFBizDocumentationSystem.adoc | 89 ++++++++++++++++++++++
docs/asciidoc/developer-manual.adoc | 2 +
docs/asciidoc/documentation_guidelines.adoc | 40 +++++++++-
docs/asciidoc/user-manual.adoc | 2 +
4 files changed, 129 insertions(+), 4 deletions(-)
diff --git a/docs/asciidoc/_include/OFBizDocumentationSystem.adoc
b/docs/asciidoc/_include/OFBizDocumentationSystem.adoc
new file mode 100644
index 0000000..652a6cf
--- /dev/null
+++ b/docs/asciidoc/_include/OFBizDocumentationSystem.adoc
@@ -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)
diff --git a/docs/asciidoc/developer-manual.adoc
b/docs/asciidoc/developer-manual.adoc
index a25d138..a770ed2 100644
--- a/docs/asciidoc/developer-manual.adoc
+++ b/docs/asciidoc/developer-manual.adoc
@@ -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]
diff --git a/docs/asciidoc/documentation_guidelines.adoc
b/docs/asciidoc/documentation_guidelines.adoc
index 88bcb6a..cc4ce09 100644
--- a/docs/asciidoc/documentation_guidelines.adoc
+++ b/docs/asciidoc/documentation_guidelines.adoc
@@ -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[]
diff --git a/docs/asciidoc/user-manual.adoc b/docs/asciidoc/user-manual.adoc
index bc7481a..3ddf0f4 100644
--- a/docs/asciidoc/user-manual.adoc
+++ b/docs/asciidoc/user-manual.adoc
@@ -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]
