This is an automated email from the ASF dual-hosted git repository.
aleks pushed a commit to branch 1.7.0
in repository https://gitbox.apache.org/repos/asf/fineract.git
The following commit(s) were added to refs/heads/1.7.0 by this push:
new 6111e6932 FINERACT-1608: Add introduction to Asciidoc
6111e6932 is described below
commit 6111e693292a66e754a266ee299c40453c89b7bc
Author: Aleks <[email protected]>
AuthorDate: Mon May 9 17:36:14 2022 +0200
FINERACT-1608: Add introduction to Asciidoc
---
README.md | 2 +-
fineract-client/build.gradle | 14 +
fineract-doc/build.gradle | 6 +-
.../documentation/asciidoc-cheatsheet.adoc | 398 +++++++++++++++++++++
.../chapters/documentation/asciidoc-tutorial.adoc | 5 -
.../docs/en/chapters/documentation/asciidoc.adoc | 8 +-
.../diagram-archimate-cheatsheet.adoc | 5 +
.../documentation/diagram-c4-cheatsheet.adoc | 5 +
.../documentation/diagram-plantuml-cheatsheet.adoc | 5 +
.../documentation/diagram-vega-cheatsheet.adoc | 5 +
.../docs/en/chapters/documentation/diagram.adoc | 13 +
.../src/docs/en/chapters/documentation/index.adoc | 6 +-
.../src/docs/en/chapters/documentation/layout.adoc | 29 +-
.../documentation/plantuml-cheatsheet.adoc | 3 -
.../chapters/documentation/plantuml-tutorial.adoc | 3 -
.../docs/en/chapters/documentation/plantuml.adoc | 9 -
.../en/chapters/release/configuration-gradle.adoc | 2 +-
.../src/docs/en/chapters/release/index.adoc | 2 +-
.../docs/en/chapters/release/process-step01.adoc | 6 +-
.../docs/en/chapters/release/process-step02.adoc | 6 +-
.../docs/en/chapters/release/process-step03.adoc | 10 +-
.../docs/en/chapters/release/process-step05.adoc | 4 +-
.../docs/en/chapters/release/process-step06.adoc | 4 +-
.../docs/en/chapters/release/process-step07.adoc | 2 +-
.../docs/en/chapters/release/process-step08.adoc | 4 +-
.../docs/en/chapters/release/process-step09.adoc | 2 +-
.../docs/en/chapters/release/process-step10.adoc | 6 +-
.../docs/en/chapters/release/process-step11.adoc | 6 +-
.../docs/en/chapters/release/process-step12.adoc | 4 +-
.../docs/en/chapters/release/process-step13.adoc | 4 +-
.../docs/en/chapters/release/process-step15.adoc | 8 +-
.../src/docs/en/chapters/security/oauth.adoc | 2 +-
.../src/docs/en/chapters/testing/cucumber.adoc | 1 +
fineract-doc/src/docs/en/colophon.adoc | 1 +
fineract-doc/src/docs/en/config.adoc | 4 +-
fineract-doc/src/docs/en/index.adoc | 19 +
fineract-provider/build.gradle | 4 +-
.../config/swagger/fineract-input.yaml.template | 8 +-
.../survey/api/SurveyApiResource.java | 3 +-
.../accounts/api/AccountsApiResource.java | 2 +-
.../api/SelfAuthenticationApiResource.java | 2 +-
.../security/api/SelfUserDetailsApiResource.java | 2 +-
.../ClasspathDuplicatesStepDefinitions.java | 6 +
43 files changed, 539 insertions(+), 101 deletions(-)
diff --git a/README.md b/README.md
index ddfd35c2b..85738369f 100644
--- a/README.md
+++ b/README.md
@@ -338,7 +338,7 @@ complies with the [Apache Software Foundation third-party
license policy](https:
Apache Fineract Platform API
============
-The API for Fineract is documented in
[apiLive.htm](fineract-provider/src/main/resources/static/api-docs/apiLive.htm),
and the [apiLive.htm can be viewed on
Fineract.dev](https://demo.fineract.dev/fineract-provider/legacy-docs/apiLive.htm
"API Documentation"). If you have your own Fineract instance running, you can
find this documentation under
[/fineract-provider/api-docs/apiLive.htm](https://localhost:8443/fineract-provider/api-docs/apiLive.htm).
+The API for Fineract is documented in
[apiLive.htm](fineract-provider/src/main/resources/static/api-docs/apiLive.htm),
and the [apiLive.htm can be viewed on
Fineract.dev](https://fineract.apache.org/legacy-docs/apiLive.htm "API
Documentation"). If you have your own Fineract instance running, you can find
this documentation under
[/fineract-provider/api-docs/apiLive.htm](https://localhost:8443/fineract-provider/api-docs/apiLive.htm).
The Swagger documentation (work in progress; see
[FINERACT-733](https://issues.apache.org/jira/browse/FINERACT-733)) can be
accessed under
[/fineract-provider/swagger-ui/index.html](https://localhost:8443/fineract-provider/swagger-ui/index.html)
and [live Swagger UI here on
Fineract.dev](https://demo.fineract.dev/fineract-provider/swagger-ui/index.html).
diff --git a/fineract-client/build.gradle b/fineract-client/build.gradle
index 717cb3652..2d9b508d9 100644
--- a/fineract-client/build.gradle
+++ b/fineract-client/build.gradle
@@ -93,6 +93,20 @@ task buildAsciidoc(type:
org.openapitools.generator.gradle.plugin.tasks.Generate
apiPackage = 'org.apache.fineract.client.services'
invokerPackage = 'org.apache.fineract.client'
modelPackage = 'org.apache.fineract.client.models'
+ configOptions = [
+ appName: 'Apache Fineract REST API',
+ appDescription: '''Apache Fineract is a secure, multi-tenanted
microfinance platform.
+ The goal of the Apache Fineract API is to empower developers to
build apps on top of the Apache Fineract Platform.
+ The https://cui.fineract.dev[reference app] (username: mifos,
password: password) works on the same demo tenant as the interactive links in
this documentation.
+ Until we complete the new REST API documentation you still have
the legacy documentation available
https://fineract.apache.org/legacy-docs/apiLive.htm[here].
+ Please check https://fineract.apache.org/docs/current[the Fineract
documentation] for more information.''',
+ headerAttributes: 'false',
+ infoEmail: '[email protected]',
+ infoUrl: 'https://fineract.apache.org',
+ licenseInfo: 'Apache 2.0',
+ licenseUrl: 'http://www.apache.org/licenses/LICENSE-2.0.html',
+ useMethodAndPath: 'true'
+ ]
dependsOn(':fineract-provider:resolve')
}
diff --git a/fineract-doc/build.gradle b/fineract-doc/build.gradle
index 8d5d6219a..f33e7a7a6 100644
--- a/fineract-doc/build.gradle
+++ b/fineract-doc/build.gradle
@@ -57,7 +57,7 @@ asciidoctor {
}
outputDir 'build/docs/html'
- dependsOn ':fineract-client:buildAsciidoc'
+ dependsOn(':fineract-client:clean', ':fineract-client:buildAsciidoc')
}
// asciidoctorEpub {
@@ -92,11 +92,11 @@ asciidoctorPdf {
// }
// }
// fontsDir "$projectDir/src/resources/fonts"
- dependsOn ':fineract-client:buildAsciidoc'
+ dependsOn(':fineract-client:clean', ':fineract-client:buildAsciidoc')
}
task doc(type: Zip) {
- dependsOn asciidoctor, asciidoctorPdf
+ dependsOn(asciidoctor, asciidoctorPdf)
into("fineract-${project.version}/html") {
from("$buildDir/docs/html") {
diff --git
a/fineract-doc/src/docs/en/chapters/documentation/asciidoc-cheatsheet.adoc
b/fineract-doc/src/docs/en/chapters/documentation/asciidoc-cheatsheet.adoc
index 58c70e86e..bf68340e8 100644
--- a/fineract-doc/src/docs/en/chapters/documentation/asciidoc-cheatsheet.adoc
+++ b/fineract-doc/src/docs/en/chapters/documentation/asciidoc-cheatsheet.adoc
@@ -1,3 +1,401 @@
= Cheatsheet
+You can find the definitive manual on AsciiDoc syntax at
https://docs.asciidoctor.org/asciidoc/latest[AsciiDoc documentation]. To help
people get started, however, here is a simpler cheat sheet.
+
+== AsciiDoc vs Asciidoctor (format vs tool)
+
+When we refer to _AsciiDoc_ then we mean the language or format that this
documentation is written in. AsciiDoc is a markup language similar to Markdown
(but more powerful and expressive) designed for technical documentation. You
don't need necessarily any specialized editors or tools to write your
documentation in AsciiDoc, a plain text editor will do, but there are plenty of
choices that give you a better experience (in this documentation we describe
the basic usage with AsciiDoc plugi [...]
+
+Asciidoctor on the other hand is the command line tool we use to transform
documents written in AsciiDoc into HTML and PDF (Epub3 and Docbook are also
available). There are three variants available:
+
+- Asciidoctor (written in Ruby)
+- Asciidoctor.js (written in JavaScript, often used for browser previews)
+- AsciidoctorJ (Java lib that integrates the Ruby implementation via JRuby, e.
g. the Asciidoctor Gradle plugin is based on that)
+
+CAUTION: Sometimes you will still find documentation related to the original
incarnation of AsciiDoc/tor (written in Python). The format evolved quite a bit
since then and the tools try to maintain a certain degree of backward
compatibility, but there is no guarantee. We prefer to use the latest language
specs as documented https://docs.asciidoctor.org/asciidoc/latest[here].
+
+== Basic AsciiDoc Syntax
+
+=== Bold
+
+Put asterisks around text to make it *bold*.
+
+NOTE: More info at https://docs.asciidoctor.org/asciidoc/latest/text/bold
+
+
+=== Italics
+
+Use underlines on either side of a string to put text into _italics_.
+
+NOTE: More info at https://docs.asciidoctor.org/asciidoc/latest/text/italic
+
+=== Headings
+
+Equal signs (`=`) are used for heading levels. Each equal sign is a level.
Each page can *only* have one top level (i.e., only one section with a single
`=`).
+
+Levels should be appropriately nested. During the build, validation occurs to
ensure that level 3s are preceded by level 2s, level 4s are preceded by level
3s, etc. Including out-of-sequence heading levels (such as a level 3 then a
level 5) will not fail the build, but will produce an error.
+
+NOTE: More info at
https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/
+
+== Code Examples
+
+Use backticks ``` for text that should be monospaced, such as code or a class
name in the body of a paragraph.
+
+NOTE: More info at https://docs.asciidoctor.org/asciidoc/latest/text/monospace/
+
+Longer code examples can be separated from text with `source` blocks.
+These allow defining the syntax being used so the code is properly highlighted.
+
+.Example Source Block
+[source,asciidoc]
+----
+[source,xml]
+<field name="id" type="string" indexed="true" stored="true" required="true"
multiValued="false" />
+----
+
+If your code block will include line breaks, put 4 hyphens (`----`) before and
after the entire block.
+
+NOTE: More info at
https://docs.asciidoctor.org/asciidoc/latest/verbatim/source-blocks/
+
+=== Source Block Syntax Highlighting
+
+The HTML output uses Rouge to add syntax highlighting to code examples. This
is done by adding the language of the code block after the `source`, as shown
in the above example source block (`xml` in that case).
+
+Rouge has a long selection of lexers available. You can see the full list at
https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers.
Use one of the valid short names to get syntax highlighting for that language.
+
+Ideally, we will have an appropriate lexer to use for all source blocks, but
that's not possible.
+When in doubt, choose `text`, or leave it blank.
+
+=== Importing Code Snippets from Other Files
+
+The build system has the ability to "include" snippets located in other files
-- even non-AsciiDoc files such as `*.java` source code files.
+
+We've configured a global attribute called `\{rootdir}` that you can use to
reference these files consistently from Fineract's project root folder.
+
+Snippets are bounded by _tag_ comments placed at the start and end of the
section you would like to import. Opening tags look like: `//
tag::snippetName[]`. Closing tags follow the format: `// end::snippetName[]`.
+
+Snippets can be inserted into an `.adoc` file using an `include` directive,
following the format:
`include::\{rootdir}/<directory-under-root-folder>/<file-name>[tag=snippetName]`.
+
+IMPORTANT: You could also use relative paths to reference include files, but
it is preferred to always use the root folder as a starting point. Like this
you can be sure that the preview in your editor of choice works.
+
+For example, if we wanted to highlight a specific section of the following
Cucumber test definition (more on that in section Cucumber Testing)
`ClasspathDuplicatesStepDefinitions.java` file located under
`fineract-provider/src/test/java/org/apache/fineract/infrastructure/classpath/`.
+
+[source,asciidoc]
+--
+[source,java,indent=0]
+----
+\include::{rootdir}/fineract-provider/src/test/java/org/apache/fineract/infrastructure/classpath/ClasspathDuplicatesStepDefinitions.java[tag=then]
+----
+--
+
+For more information on the `include` directive, see the documentation at
https://docs.asciidoctor.org/asciidoc/latest/directives/include.
+
+=== Block Titles
+
+Titles can be added to most blocks (images, source blocks, tables, etc.) by
simply prefacing the title with a period (`.`). For example, to add a title to
the source block example above:
+
+[source,asciidoc]
+----
+.Example ID field
+[source,xml]
+<field name="id" type="string" indexed="true" stored="true" required="true"
multiValued="false" />
+----
+
+NOTE: More info at
https://docs.asciidoctor.org/asciidoc/latest/blocks/add-title
+
+== Links
+
+=== Link to Sites on the Internet
+
+When converting content to HTML, Asciidoctor will automatically render many
link types (such as `http:` and `mailto:`) without any additional syntax.
However, you can add a name to a link by adding the URI followed by square
brackets:
+
+[source,asciidoc]
+----
+http://fineract.apache.org/[Fineract Website]
+----
+
+NOTE: More info at
https://docs.asciidoctor.org/asciidoc/latest/macros/url-macro
+
+=== Link to Other Pages/Sections of the Guide
+
+A warning up front, linking to other pages can be a little painful. There are
slightly different rules depending on the type of link you want to create, and
where you are linking from. The build process includes a validation for
_internal_ or _inter-page_ links, so if you can build the docs locally, you can
use that to verify you constructed your link properly. With all the below
examples, you can add text to display as the link title by putting the display
text in brackets after the lin [...]
+
+[source,asciidoc]
+----
+xref:indexing-guide:schema-api.adoc#modify-the-schema[Modify the Schema]
+----
+
+You can also use the title of the Page or Section you are linking to by using
an empty display text.
+This is useful in case the title of the page or section changes. In that case
you won't need to change the display text for every link that refers to that
page/section.
+
+See an example below:
+
+[source,asciidoc]
+----
+xref:indexing-guide:schema-api.adoc#modify-the-schema[]
+----
+
+==== Link to a Section on the Same Page
+
+To link to an anchor (or section title) on the _same page_, you can simply use
double angle brackets (`<< >>`) around the anchor/heading/section title you
want to link to. Any section title (a heading that starts with equal signs)
automatically becomes an anchor during conversion and is available for deep
linking.
+
+Example::
+If I have a section on a page that looks like this (from `process.adoc`):
++
+[source,asciidoc]
+----
+== Steps
+
+Common parameters for all steps are:
+----
++
+To link to this section from another part of the same `process.adoc` page, I
simply need to put the section title in double angle brackets, as in:
++
+[source,asciidoc]
+See also the <<Steps>> section.
++
+The section title will be used as the display text; to customize that add a
comma after the the section title, then the text you want used for display.
+
+NOTE: More info at
https://docs.asciidoctor.org/asciidoc/latest/macros/xref/#internal-cross-references
+
+==== Link to a Section with an Anchor ID
+
+When linking to any section (on the same page or another one), you must also
be aware of any pre-defined anchors that may be in use (these will be in double
brackets, like `[[ ]]`).
+When the page is converted, those will be the references your link needs to
point to.
+
+Example::
+Take this example from `configsets-api.adoc`:
++
+[source,asciidoc]
+----
+[[configsets-create]]
+== Create a ConfigSet
+----
++
+To link to this section, there are two approaches depending on where you are
linking from:
+
+* From the same page, simply use the anchor name: `\<<configsets-create>>`.
+* From another page, use the page name and the anchor name:
`\xref:configuration-guide:configsets-api.adoc#configsets-create[]`.
+
+==== Link to Another Page
+
+To link to _another page_ or a section on another page, you must refer to the
full filename and refer to the section you want to link to.
+
+When you want to refer the reader to another page without deep-linking to a
section, Asciidoctor allows this by merely omitting the `#` and section id.
+
+Example::
+To construct a link to the `process.adoc` page, we need to refer to the file
name (`process.adoc`), as well as the module that the file resides in
(`release/`).
++
+It's preferred to also always use the page name to give the reader better
context for where the link goes.
+As in:
++
+[source,asciidoc]
+----
+For more about upgrades, see xref:release:process.adoc[Fineract Release
Process].
+----
+
+==== Link to Another Page in the same folder
+
+If the page that contains the link and the page being linked to reside in the
same module, there is no need to include the module name after `xref:`
+
+Example::
+To construct a link to the `process-step01.adoc` page from `process.adoc`
page, we do not need to include the module name because they both reside in the
`upgrade-notes` module.
++
+[source,asciidoc]
+----
+For more information on the first step of the release process, see the section
\xref:process-step01.adoc[].
+----
+
+==== Link to a Section on Another Page
+
+Linking to a section is the same conceptually as linking to the top of a page,
you just need to take a little extra care to format the anchor ID in your link
reference properly.
+
+When you link to a section on another page, you must make a simple conversion
of the title into the format of the section ID that will be created during the
conversion. These are the rules that transform the sections:
+
+Example::
TBD
+
+NOTE: More info at
https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref
+
+== Ordered and Unordered Lists
+
+AsciiDoc supports three types of lists:
+
+* Unordered lists
+* Ordered lists
+* Labeled lists
+
+Each type of list can be mixed with the other types. So, you could have an
ordered list inside a labeled list if necessary.
+
+=== Unordered Lists
+
+Simple bulleted lists need each line to start with an asterisk (`*`). It
should be the first character of the line, and be followed by a space.
+
+NOTE: More info at https://docs.asciidoctor.org/asciidoc/latest/lists/unordered
+
+=== Ordered Lists
+
+Numbered lists need each line to start with a period (`.`). It should be the
first character of the line, and be followed by a space. This style is
preferred over manually numbering your list.
+
+NOTE: More info at https://docs.asciidoctor.org/asciidoc/latest/lists/ordered
+
+=== Description Lists
+
+These are like question & answer lists or glossary definitions.
+Each line should start with the list item followed by double colons (`::`),
then a space or new line. Labeled lists can be nested by adding an additional
colon (such as `:::`, etc.). If your content will span multiple paragraphs or
include source blocks, etc., you will want to add a plus sign (`+`) to keep the
sections together for your reader.
+
+TIP: We prefer this style of list for parameters because it allows more
freedom in how you present the details for each parameter. For example, it
supports ordered or unordered lists inside it automatically, and you can
include multiple paragraphs and source blocks without trying to cram them into
a smaller table cell.
+
+NOTE: More info at
https://docs.asciidoctor.org/asciidoc/latest/lists/description
+
+== Images
+
+There are two ways to include an image: inline or as a block. Inline images
are those where text will flow around the image. Block images are those that
appear on their own line, set off from any other text on the page. Both
approaches use the `image` tag before the image filename, but the number of
colons after `image` define if it is inline or a block. Inline images use one
colon (`image:`), while block images use two colons (`image::`). Block images
automatically include a caption lab [...]
+
+NOTE: More info at https://docs.asciidoctor.org/asciidoc/latest/macros/images
+
+== Tables
+
+Tables can be complex, but it is pretty easy to make a basic table that fits
most needs.
+
+=== Basic Tables
+
+The basic structure of a table is similar to Markdown, with pipes (`|`)
delimiting columns between rows:
+
+[source,asciidoc]
+----
+|===
+| col 1 row 1 | col 2 row 1|
+| col 1 row 2 | col 2 row 2|
+|===
+----
+
+Note the use of `|===` at the start and end. For basic tables that's not
exactly required, but it does help to delimit the start and end of the table in
case you accidentally introduce (or maybe prefer) spaces between the rows.
+
+=== Header Rows
+
+To add a header to a table, you need only set the `header` attribute at the
start of the table:
+
+[source,asciidoc]
+----
+[options="header"]
+|===
+| header col 1 | header col 2|
+| col 1 row 1 | col 2 row 1|
+| col 1 row 2 | col 2 row 2|
+|===
+----
+
+=== Defining Column Styles
+
+If you need to define specific styles to all rows in a column, you can do so
with the attributes.
+
+This example will center all content in all rows:
+
+[source,asciidoc]
+----
+[cols="2*^" options="header"]
+|===
+| header col 1 | header col 2|
+| col 1 row 1 | col 2 row 1|
+| col 1 row 2 | col 2 row 2|
+|===
+----
+
+Alignments or any other styles can be applied only to a specific column. For
example, this would only center the last column of the table:
+
+[source,asciidoc]
+----
+[cols="2*,^" options="header"]
+|===
+| header col 1 | header col 2|
+| col 1 row 1 | col 2 row 1|
+| col 1 row 2 | col 2 row 2|
+|===
+----
+
+[NOTE]
+.Many more examples of formatting:
+====
+* Columns: https://docs.asciidoctor.org/asciidoc/latest/tables/add-columns/
+* Cells and rows:
https://docs.asciidoctor.org/asciidoc/latest/tables/add-cells-and-rows/
+====
+
+=== More Options
+
+Tables can also be given footer rows, borders, and captions. You can
determine the width of columns, or the width of the table as a whole.
+
+CSV or DSV can also be used instead of formatting the data in pipes.
+
+NOTE: More info at
https://docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/
+
+== Admonitions (Notes, Warnings)
+
+AsciiDoc supports several types of callout boxes, called "admonitions":
+
+* NOTE
+* TIP
+* IMPORTANT
+* CAUTION
+* WARNING
+
+It is enough to start a paragraph with one of these words followed by a colon
(such as `NOTE:`). When it is converted to HTML, those sections will be
formatted properly - indented from the main text and showing an icon inline.
+
+You can add titles to admonitions by making it an admonition block. The
structure of an admonition block is like this:
+
+[source,asciidoc]
+----
+.Title of Note
+[NOTE]
+====
+Text of note
+====
+----
+
+In this example, the type of admonition is included in square brackets
(`[NOTE]`), and the title is prefixed with a period. Four equal signs give the
start and end points of the note text (which can include new lines, lists, code
examples, etc.).
+
+NOTE: More info at
https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/
+
+== STEM Notation Support
+
+We have set up the Ref Guide to be able to support STEM notation whenever it's
needed.
+
+The http://asciimath.org/[AsciiMath] syntax is supported by default, but LaTeX
syntax is also available.
+
+To insert a mathematical formula inline with your text, you can simply write:
+
+[source,asciidoc]
+----
+stem:[a//b]
+----
+
+MathJax.js will render the formula as proper mathematical notation when a user
loads the page. When the above example is converted to HTML, it will look like
this to a user: stem:[a//b]
+
+To insert LaTeX, preface the formula with `latexmath` instead of `stem`:
+
+[source,asciidoc]
+----
+latexmath:[tp \leq 1 - (1 - sim^{rows})^{bands}]
+----
+
+Long formulas, or formulas which should to be set off from the main text, can
use the block syntax prefaced by `stem` or `latexmath`:
+
+[source,asciidoc]
+----
+[stem]
+++++
+sqrt(3x-1)+(1+x)^2 < y
+++++
+----
+
+or for LaTeX:
+
+[source,asciidoc]
+----
+[latexmath]
+++++
+[tp \leq 1 - (1 - sim^{rows})^{bands}]
+++++
+----
+
+NOTE: More info at https://docs.asciidoctor.org/asciidoc/latest/stem/stem
diff --git
a/fineract-doc/src/docs/en/chapters/documentation/asciidoc-tutorial.adoc
b/fineract-doc/src/docs/en/chapters/documentation/asciidoc-tutorial.adoc
deleted file mode 100644
index 3af79bf1c..000000000
--- a/fineract-doc/src/docs/en/chapters/documentation/asciidoc-tutorial.adoc
+++ /dev/null
@@ -1,5 +0,0 @@
-= Tutorial
-
-See: https://www.vogella.com/tutorials/AsciiDoc/article.html
-
-TBD
diff --git a/fineract-doc/src/docs/en/chapters/documentation/asciidoc.adoc
b/fineract-doc/src/docs/en/chapters/documentation/asciidoc.adoc
index 2e4f79198..353585991 100644
--- a/fineract-doc/src/docs/en/chapters/documentation/asciidoc.adoc
+++ b/fineract-doc/src/docs/en/chapters/documentation/asciidoc.adoc
@@ -1,9 +1,3 @@
-= Asciidoc
-
-See: https://asciidoctor.org/
-
-TBD
-
-include::asciidoc-tutorial.adoc[leveloffset=+1]
+= AsciiDoc
include::asciidoc-cheatsheet.adoc[leveloffset=+1]
diff --git
a/fineract-doc/src/docs/en/chapters/documentation/diagram-archimate-cheatsheet.adoc
b/fineract-doc/src/docs/en/chapters/documentation/diagram-archimate-cheatsheet.adoc
new file mode 100644
index 000000000..5f7a5d016
--- /dev/null
+++
b/fineract-doc/src/docs/en/chapters/documentation/diagram-archimate-cheatsheet.adoc
@@ -0,0 +1,5 @@
+= Archimate Cheatsheet
+
+TBD
+
+NOTE: https://www.opengroup.org/archimate-forum/archimate-overview and
https://plantuml.com/archimate-diagram
\ No newline at end of file
diff --git
a/fineract-doc/src/docs/en/chapters/documentation/diagram-c4-cheatsheet.adoc
b/fineract-doc/src/docs/en/chapters/documentation/diagram-c4-cheatsheet.adoc
new file mode 100644
index 000000000..8c2691c40
--- /dev/null
+++ b/fineract-doc/src/docs/en/chapters/documentation/diagram-c4-cheatsheet.adoc
@@ -0,0 +1,5 @@
+= C4 Cheatsheet
+
+TBD
+
+NOTE: https://c4model.com and https://github.com/plantuml-stdlib/C4-PlantUML
\ No newline at end of file
diff --git
a/fineract-doc/src/docs/en/chapters/documentation/diagram-plantuml-cheatsheet.adoc
b/fineract-doc/src/docs/en/chapters/documentation/diagram-plantuml-cheatsheet.adoc
new file mode 100644
index 000000000..dc668b9e6
--- /dev/null
+++
b/fineract-doc/src/docs/en/chapters/documentation/diagram-plantuml-cheatsheet.adoc
@@ -0,0 +1,5 @@
+= PlantUML Cheatsheet
+
+TBD
+
+NOTE: https://plantuml.com
\ No newline at end of file
diff --git
a/fineract-doc/src/docs/en/chapters/documentation/diagram-vega-cheatsheet.adoc
b/fineract-doc/src/docs/en/chapters/documentation/diagram-vega-cheatsheet.adoc
new file mode 100644
index 000000000..a7e79a01c
--- /dev/null
+++
b/fineract-doc/src/docs/en/chapters/documentation/diagram-vega-cheatsheet.adoc
@@ -0,0 +1,5 @@
+= Vega Cheatsheet
+
+TBD
+
+NOTE: https://vega.github.io/vega-lite/
\ No newline at end of file
diff --git a/fineract-doc/src/docs/en/chapters/documentation/diagram.adoc
b/fineract-doc/src/docs/en/chapters/documentation/diagram.adoc
new file mode 100644
index 000000000..b6327330e
--- /dev/null
+++ b/fineract-doc/src/docs/en/chapters/documentation/diagram.adoc
@@ -0,0 +1,13 @@
+= Diagrams
+
+TBD
+
+NOTE: https://docs.asciidoctor.org/diagram-extension/latest
+
+include::diagram-plantuml-cheatsheet.adoc[leveloffset=+1]
+
+include::diagram-c4-cheatsheet.adoc[leveloffset=+1]
+
+include::diagram-archimate-cheatsheet.adoc[leveloffset=+1]
+
+include::diagram-vega-cheatsheet.adoc[leveloffset=+1]
diff --git a/fineract-doc/src/docs/en/chapters/documentation/index.adoc
b/fineract-doc/src/docs/en/chapters/documentation/index.adoc
index 7ac4570c4..9b0450878 100644
--- a/fineract-doc/src/docs/en/chapters/documentation/index.adoc
+++ b/fineract-doc/src/docs/en/chapters/documentation/index.adoc
@@ -1,6 +1,4 @@
-= Documentation
-
-We try to assemble all Fineract related documentation in this document. We use
Asciidoc...
+= Fineract Documentation Guide
TBD
@@ -8,7 +6,7 @@ include::layout.adoc[leveloffset=+1]
include::asciidoc.adoc[leveloffset=+1]
-include::plantuml.adoc[leveloffset=+1]
+include::diagram.adoc[leveloffset=+1]
include::editor.adoc[leveloffset=+1]
diff --git a/fineract-doc/src/docs/en/chapters/documentation/layout.adoc
b/fineract-doc/src/docs/en/chapters/documentation/layout.adoc
index 66a67da2a..93fc21567 100644
--- a/fineract-doc/src/docs/en/chapters/documentation/layout.adoc
+++ b/fineract-doc/src/docs/en/chapters/documentation/layout.adoc
@@ -1,19 +1,14 @@
= File and Folder Layout
-TBD
-
-== Book
-
-TBD
-
-== Chapter
-
-TBD
-
-== Diagrams
-
-TBD
-
-== Images
-
-TBD
+The general rules are::
+
+* keep things as flat as possible (avoid sub-folders as much as possible)
+* DRY (don't repeat yourself): don't copy and paste code pieces, use
AsciiDoc's include feature and reference files/-sections from the project folder
+* images are located in `fineract-doc/src/docs/en/images` (or sub-folders)
+* diagrams are located in `fineract-doc/src/docs/en/diagrams` (or sub-folders)
+* specific chapters are located in `fineract-doc/src/docs/en/chapters`
+* every chapter has its own folder and at least one `index.adoc` file
+* it's recommended to keep the chapters flat (i. e. no sub-folders in the
chapter folders)
+* it's recommended to create one file per chapter section; like that you can
re-arrange sections very easily in the `index.adoc` file
+
+NOTE: These rules are not entirely set in stone and could be modified if
necessary. If you see any issues then please report them on the
mailto:[email protected][mailing list] or https://issues.apache.org[open
a Jira ticket].
diff --git
a/fineract-doc/src/docs/en/chapters/documentation/plantuml-cheatsheet.adoc
b/fineract-doc/src/docs/en/chapters/documentation/plantuml-cheatsheet.adoc
deleted file mode 100644
index 58c70e86e..000000000
--- a/fineract-doc/src/docs/en/chapters/documentation/plantuml-cheatsheet.adoc
+++ /dev/null
@@ -1,3 +0,0 @@
-= Cheatsheet
-
-TBD
diff --git
a/fineract-doc/src/docs/en/chapters/documentation/plantuml-tutorial.adoc
b/fineract-doc/src/docs/en/chapters/documentation/plantuml-tutorial.adoc
deleted file mode 100644
index b704924d7..000000000
--- a/fineract-doc/src/docs/en/chapters/documentation/plantuml-tutorial.adoc
+++ /dev/null
@@ -1,3 +0,0 @@
-= Tutorial
-
-TBD
diff --git a/fineract-doc/src/docs/en/chapters/documentation/plantuml.adoc
b/fineract-doc/src/docs/en/chapters/documentation/plantuml.adoc
deleted file mode 100644
index 10cd7506c..000000000
--- a/fineract-doc/src/docs/en/chapters/documentation/plantuml.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-= PlantUML
-
-See: https://plantuml.com/
-
-TBD
-
-include::plantuml-tutorial.adoc[leveloffset=+1]
-
-include::plantuml-cheatsheet.adoc[leveloffset=+1]
diff --git
a/fineract-doc/src/docs/en/chapters/release/configuration-gradle.adoc
b/fineract-doc/src/docs/en/chapters/release/configuration-gradle.adoc
index d3df3b5eb..2cec0fcc1 100644
--- a/fineract-doc/src/docs/en/chapters/release/configuration-gradle.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/configuration-gradle.adoc
@@ -34,5 +34,5 @@ Creating Apache Fineract releases was a very manual and
tedious procedure before
[source,groovy]
----
-include::{rootdir}/buildSrc/src/main/groovy/org.apache.fineract.release.gradle[lines=32..105]
+include::{rootdir}/buildSrc/src/main/groovy/org.apache.fineract.release.gradle[lines=23..89]
----
diff --git a/fineract-doc/src/docs/en/chapters/release/index.adoc
b/fineract-doc/src/docs/en/chapters/release/index.adoc
index 1c663ab8c..8bbfe89e5 100644
--- a/fineract-doc/src/docs/en/chapters/release/index.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/index.adoc
@@ -3,7 +3,7 @@
https://cwiki.apache.org/confluence/x/DRwIB[How to Release Apache Fineract]
documents the process how we make the source code that is available here in
this Git repository into a binary release tar.gz available on
http://fineract.apache.org.
.Release Schedule
-[plantuml, format=svg]
+[plantuml, format=svg, width=100%]
----
include::{diagramsdir}/release-schedule.puml[]
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step01.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step01.adoc
index 364106669..929e99cba 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step01.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step01.adoc
@@ -12,15 +12,15 @@ The RM should then inform users when the git branch is
planned to be created, by
[source,text]
----
-include::{rootdir}/buildSrc/src/main/resources/email/release.step01.headsup.subject.ftl[]
+include::{rootdir}/buildSrc/src/main/resources/email/release.step01.headsup.subject.ftl[lines=21..]
-include::{rootdir}/buildSrc/src/main/resources/email/release.step01.headsup.message.ftl[]
+include::{rootdir}/buildSrc/src/main/resources/email/release.step01.headsup.message.ftl[lines=21..]
----
== Gradle Task
.Command
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep1 -Pfineract.release.issue=1234
-Pfineract.release.date="Monday, April 25, 2022"
-Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step02.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step02.adoc
index 1bbb05fb0..b126d0fa1 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step02.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step02.adoc
@@ -10,13 +10,13 @@ project = FINERACT and resolution = fixed and fixVersion is
empty
----
Move all unresolved JIRA issues which have this release as Fix Version to the
next release
-[source,text,subs="attributes"]
+[source,text,subs="attributes+,+macros"]
----
project = FINERACT and fixVersion = {revnumber} and status not in ( Resolved,
Done, Accepted, Closed )
----
You can also run the following query to make sure that the issues fixed for
the to-be-released version look accurate:
-[source,text,subs="attributes"]
+[source,text,subs="attributes+,+macros"]
----
project = FINERACT and fixVersion = {revnumber}
----
@@ -26,7 +26,7 @@ Finally, check out the output of the JIRA release note tool
to see which tickets
== Gradle Task
.Command
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep2 -Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step03.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step03.adoc
index 3f142a6bd..daee60517 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step03.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step03.adoc
@@ -24,14 +24,14 @@ You do not need to ask committers to hold off any commits
until you have branche
1. Create a new release branch with name "$Version"
+
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% git checkout -b {revnumber}
----
1. Push new branch to Apache Fineract repository
+
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% git push origin {revnumber}
----
@@ -42,15 +42,15 @@ You do not need to ask committers to hold off any commits
until you have branche
+
[source,text]
----
-include::{rootdir}/buildSrc/src/main/resources/email/release.step03.branch.subject.ftl[]
+include::{rootdir}/buildSrc/src/main/resources/email/release.step03.branch.subject.ftl[lines=21..]
-include::{rootdir}/buildSrc/src/main/resources/email/release.step03.branch.message.ftl[]
+include::{rootdir}/buildSrc/src/main/resources/email/release.step03.branch.message.ftl[lines=21..]
----
== Gradle Task
.Command
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep3 -Pfineract.release.date="Monday, May 10,
2022" -Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step05.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step05.adoc
index bafbae123..8288ef1c9 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step05.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step05.adoc
@@ -4,7 +4,7 @@
Next, you create a git tag from the HEAD of the release's git branch.
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% git checkout {revnumber}
% ./gradlew clean integrationTests <1>
@@ -18,7 +18,7 @@ CAUTION: It is important to create so called annotated tags
(vs. lightweight) fo
== Gradle Task
.Command
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep5 -Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step06.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step06.adoc
index e9326faa0..e0a8ceab8 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step06.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step06.adoc
@@ -4,7 +4,7 @@
Create source and binary artifacts. Make sure to do some sanity checks. The
tar and the release branch should match.
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% cd /fineract-release-preparations <1>
% tar -xvf apache-fineract-{revnumber}-src.tar.gz
@@ -18,7 +18,7 @@ Create source and binary artifacts. Make sure to do some
sanity checks. The tar
Make sure code compiles and tests pass on the uncompressed source.
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% cd apache-fineract-{revnumber}-src/fineract-provider <1>
% gradlew clean integrationTest <2>
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step07.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step07.adoc
index 169a61cb3..cbc2e6945 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step07.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step07.adoc
@@ -4,7 +4,7 @@
All release artifacts must be signed. In order to sign a release you will need
a PGP key. You should get your key signed by a few other people. You will also
need to receive their keys from a public key server. See the Apache release
signing page for more details. Please follow the steps defined in Release Sign.
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% gpg --armor --output apache-fineract-{revnumber}-src.tar.gz.asc --detach-sig
apache-fineract-{revnumber}-src.tar.gz
% gpg --print-md MD5 apache-fineract-{revnumber}-src.tar.gz >
apache-fineract-{revnumber}-src.tar.gz.md5
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step08.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step08.adoc
index a954973c2..fecf7786b 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step08.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step08.adoc
@@ -15,7 +15,7 @@ Finally create a directory with release name ({revnumber} in
this example) in ht
Upload binary and source archives to ASF's distribution dev (staging) area:
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% svn co https://dist.apache.org/repos/dist/dev/fineract/ fineract-dist-dev
% mkdir fineract-dist-dev/{revnumber}
@@ -28,7 +28,7 @@ NOTE: You will need your ASF Committer credentials to be able
to access the Subv
== Gradle Task
.Command
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep8 -Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step09.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step09.adoc
index ecb5feeb5..ffebe3f20 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step09.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step09.adoc
@@ -18,7 +18,7 @@ Make sure release artifacts are hosted at
https://dist.apache.org/repos/dist/dev
== Gradle Task
.Command
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep9 -Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step10.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step10.adoc
index d27916112..eb36cdc23 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step10.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step10.adoc
@@ -6,15 +6,15 @@ Voting has to be done on [email protected]. You can
close the vote after v
[source,text]
----
-include::{rootdir}/buildSrc/src/main/resources/email/release.step10.vote.subject.ftl[]
+include::{rootdir}/buildSrc/src/main/resources/email/release.step10.vote.subject.ftl[lines=21..]
-include::{rootdir}/buildSrc/src/main/resources/email/release.step10.vote.message.ftl[]
+include::{rootdir}/buildSrc/src/main/resources/email/release.step10.vote.message.ftl[lines=21..]
----
== Gradle Task
.Command
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep10 -Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step11.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step11.adoc
index e00de88ec..01134f86b 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step11.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step11.adoc
@@ -6,15 +6,15 @@ Upon receiving 3 x +1 from the PMC, or after 72 hours
(whichever one comes first
[source,text]
----
-include::{rootdir}/buildSrc/src/main/resources/email/release.step11.vote.subject.ftl[]
+include::{rootdir}/buildSrc/src/main/resources/email/release.step11.vote.subject.ftl[lines=21..]
-include::{rootdir}/buildSrc/src/main/resources/email/release.step11.vote.message.ftl[]
+include::{rootdir}/buildSrc/src/main/resources/email/release.step11.vote.message.ftl[lines=21..]
----
== Gradle Task
.Command
-[source,text,subs="attributes"]
+[source,text,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep11 -Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step12.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step12.adoc
index b93fd7f74..979b6e854 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step12.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step12.adoc
@@ -4,7 +4,7 @@
In order to release you have to checkout release repository located on
https://dist.apache.org/repos/dist/release/fineract and add release artifacts
there.
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% svn co https://dist.apache.org/repos/dist/release/fineract fineract-release
% mkdir fineract-release/{revnumber}/
@@ -18,7 +18,7 @@ You will now get an automated email from the Apache Reporter
Service (no-reply@r
== Gradle Task
.Command
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep12 -Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step13.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step13.adoc
index 49a2725f8..131f1cbad 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step13.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step13.adoc
@@ -4,7 +4,7 @@
As discussed in
https://issues.apache.org/jira/browse/FINERACT-1154[FINERACT-1154], now that
everything is final, please do the following to remove the release branch (and
just keep the tag), and make sure that everything on the release tag is merged
to develop and that e.g. git describe works:
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% git checkout develop
% git branch -D {revnumber}
@@ -21,7 +21,7 @@ As discussed in
https://issues.apache.org/jira/browse/FINERACT-1154[FINERACT-115
== Gradle Task
.Command
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep13 -Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/release/process-step15.adoc
b/fineract-doc/src/docs/en/chapters/release/process-step15.adoc
index 5e85ee1cd..8ccc7d1e8 100644
--- a/fineract-doc/src/docs/en/chapters/release/process-step15.adoc
+++ b/fineract-doc/src/docs/en/chapters/release/process-step15.adoc
@@ -2,19 +2,19 @@
== Description
-Send an email to [email protected] (sender address must be @apache.org):
+Send an email to `[email protected]` (sender address must be `@apache.org`):
[source,text]
----
-include::{rootdir}/buildSrc/src/main/resources/email/release.step15.announce.subject.ftl[]
+include::{rootdir}/buildSrc/src/main/resources/email/release.step15.announce.subject.ftl[lines=21..]
-include::{rootdir}/buildSrc/src/main/resources/email/release.step15.announce.message.ftl[]
+include::{rootdir}/buildSrc/src/main/resources/email/release.step15.announce.message.ftl[lines=21..]
----
== Gradle Task
.Command
-[source,bash,subs="attributes"]
+[source,bash,subs="attributes+,+macros"]
----
% ./gradlew fineractReleaseStep15 -Pfineract.release.version={revnumber}
----
diff --git a/fineract-doc/src/docs/en/chapters/security/oauth.adoc
b/fineract-doc/src/docs/en/chapters/security/oauth.adoc
index 8f7909d87..74a9e9c00 100644
--- a/fineract-doc/src/docs/en/chapters/security/oauth.adoc
+++ b/fineract-doc/src/docs/en/chapters/security/oauth.adoc
@@ -63,4 +63,4 @@ curl --location --request GET \
----
-NOTE: See also
https://demo.fineract.dev/fineract-provider/legacy-docs/apiLive.htm#authentication_oauth
+NOTE: See also
https://fineract.apache.org/legacy-docs/apiLive.htm#authentication_oauth
diff --git a/fineract-doc/src/docs/en/chapters/testing/cucumber.adoc
b/fineract-doc/src/docs/en/chapters/testing/cucumber.adoc
index 81a578358..90c356bb4 100644
--- a/fineract-doc/src/docs/en/chapters/testing/cucumber.adoc
+++ b/fineract-doc/src/docs/en/chapters/testing/cucumber.adoc
@@ -1,3 +1,4 @@
+[[testing-cucumber]]
= Cucumber
TBD
diff --git a/fineract-doc/src/docs/en/colophon.adoc
b/fineract-doc/src/docs/en/colophon.adoc
index 1454f104c..3a0e713da 100644
--- a/fineract-doc/src/docs/en/colophon.adoc
+++ b/fineract-doc/src/docs/en/colophon.adoc
@@ -34,6 +34,7 @@
| Arnold Galovics | Database architecture section | 2022-03-11 | 1.7.0
| Aleksandar Vidakovic | Module section | 2022-03-23 | 1.7.0
| Aleksandar Vidakovic | Release section, file re-organisation | 2022-04-18 |
1.7.0
+| Aleksandar Vidakovic | AsciiDoc cheatsheet | 2022-05-09 | 1.7.0
|===
toc::[]
diff --git a/fineract-doc/src/docs/en/config.adoc
b/fineract-doc/src/docs/en/config.adoc
index f6f597849..0cc9b3326 100644
--- a/fineract-doc/src/docs/en/config.adoc
+++ b/fineract-doc/src/docs/en/config.adoc
@@ -8,8 +8,8 @@
:pdf-version: 1.7
:page-layout: base
:toc-title: Table of Contents
-:toc: macro
-:toclevels: 4
+:toc: left
+:toclevels: 2
:icons: font
:source-highlighter: coderay
:experimental:
diff --git a/fineract-doc/src/docs/en/index.adoc
b/fineract-doc/src/docs/en/index.adoc
index 2b77c7112..d030fbd32 100644
--- a/fineract-doc/src/docs/en/index.adoc
+++ b/fineract-doc/src/docs/en/index.adoc
@@ -1,3 +1,22 @@
+//
+// 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.
+//
+
:doctitle: Fineract Platform Documentation
include::config.adoc[]
diff --git a/fineract-provider/build.gradle b/fineract-provider/build.gradle
index d6e38a943..84ac3e8fa 100644
--- a/fineract-provider/build.gradle
+++ b/fineract-provider/build.gradle
@@ -70,9 +70,9 @@ resolve {
prettyPrint = false
classpath = sourceSets.main.runtimeClasspath
outputDir = file("${buildDir}/classes/java/main/static")
- // openApiFile = file("${buildDir}/tmp/swagger/fineract-input.yaml")
+ openApiFile = file("${buildDir}/tmp/swagger/fineract-input.yaml")
sortOutput = true
- // dependsOn(prepareInputYaml)
+ dependsOn(prepareInputYaml)
}
configurations {
diff --git a/fineract-provider/config/swagger/fineract-input.yaml.template
b/fineract-provider/config/swagger/fineract-input.yaml.template
index 3202c903a..f7abfe93c 100644
--- a/fineract-provider/config/swagger/fineract-input.yaml.template
+++ b/fineract-provider/config/swagger/fineract-input.yaml.template
@@ -1,13 +1,13 @@
openapi: 3.0.3
info:
version: @VERSION@
- title: Apache Fineract
+ title: Apache Fineract REST API
description: |-
Apache Fineract is a secure, multi-tenanted microfinance platform.
The goal of the Apache Fineract API is to empower developers to build apps
on top of the Apache Fineract Platform.
- The <a href="https://cui.fineract.dev"; target="_blank">reference app</a>
(username: mifos, password: password) works on the same demo tenant as the
interactive links in this documentation.
- Until we complete the new REST API documentation you still have the legacy
documentation available <a href="../legacy-docs/apiLive.htm"
target="_blank">here</a>.
- Please check <a href="https://fineract.apache.org/docs/current";
target="_blank">the Fineract documentation</a> for more information.
+ The https://cui.fineract.dev[reference app] (username: mifos, password:
password) works on the same demo tenant as the interactive links in this
documentation.
+ Until we complete the new REST API documentation you still have the legacy
documentation available
https://fineract.apache.org/legacy-docs/apiLive.htm[here].
+ Please check https://fineract.apache.org/docs/current[the Fineract
documentation] for more information.
contact:
email: [email protected]
license:
diff --git
a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/survey/api/SurveyApiResource.java
b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/survey/api/SurveyApiResource.java
index 2cf9acad4..19bc1aa31 100644
---
a/fineract-provider/src/main/java/org/apache/fineract/infrastructure/survey/api/SurveyApiResource.java
+++
b/fineract-provider/src/main/java/org/apache/fineract/infrastructure/survey/api/SurveyApiResource.java
@@ -119,8 +119,7 @@ public class SurveyApiResource {
@Consumes({ MediaType.APPLICATION_JSON })
@Produces({ MediaType.APPLICATION_JSON })
@Operation(summary = "Create an entry in the survey table", description =
"Insert and entry in a survey table (full fill the survey)."
- + "\n" + "\n"
- + "Refer Link for sample Body: [
https://demo.fineract.dev/fineract-provider/legacy-docs/apiLive.htm#survey_create
] ")
+ + "\n" + "\n" + "Refer Link for sample Body: [
https://fineract.apache.org/legacy-docs/apiLive.htm#survey_create ] ")
@RequestBody(required = true, content = @Content(schema =
@Schema(implementation =
SurveyApiResourceSwagger.PostSurveySurveyNameApptableIdRequest.class)))
@ApiResponses({
@ApiResponse(responseCode = "200", description = "OK", content =
@Content(schema = @Schema(implementation =
SurveyApiResourceSwagger.PostSurveySurveyNameApptableIdResponse.class))) })
diff --git
a/fineract-provider/src/main/java/org/apache/fineract/portfolio/accounts/api/AccountsApiResource.java
b/fineract-provider/src/main/java/org/apache/fineract/portfolio/accounts/api/AccountsApiResource.java
index 6489e4b60..43cb3da5e 100644
---
a/fineract-provider/src/main/java/org/apache/fineract/portfolio/accounts/api/AccountsApiResource.java
+++
b/fineract-provider/src/main/java/org/apache/fineract/portfolio/accounts/api/AccountsApiResource.java
@@ -200,7 +200,7 @@ public class AccountsApiResource {
+ "requestedDate is requsted date of shares redeem\n" + "\n" +
"requestedShares is number of shares to be redeemed\n\n"
+ "Mandatory Fields:
dateFormat,locale,requestedDate,requestedShares\n\n"
+ "Showing request/response for 'Reject additional shares request
on a share account'\n\n"
- + "For more info visit this link -
https://demo.fineract.dev/fineract-provider/legacy-docs/apiLive.htm#shareaccounts";)
+ + "For more info visit this link -
https://fineract.apache.org/legacy-docs/apiLive.htm#shareaccounts";)
@RequestBody(required = true, content = @Content(schema =
@Schema(implementation =
AccountsApiResourceSwagger.PostAccountsTypeAccountIdRequest.class)))
@ApiResponses({
@ApiResponse(responseCode = "200", description = "OK", content =
@Content(schema = @Schema(implementation =
AccountsApiResourceSwagger.PostAccountsTypeAccountIdResponse.class))) })
diff --git
a/fineract-provider/src/main/java/org/apache/fineract/portfolio/self/security/api/SelfAuthenticationApiResource.java
b/fineract-provider/src/main/java/org/apache/fineract/portfolio/self/security/api/SelfAuthenticationApiResource.java
index 784912de2..e5d3cd2a8 100644
---
a/fineract-provider/src/main/java/org/apache/fineract/portfolio/self/security/api/SelfAuthenticationApiResource.java
+++
b/fineract-provider/src/main/java/org/apache/fineract/portfolio/self/security/api/SelfAuthenticationApiResource.java
@@ -53,7 +53,7 @@ public class SelfAuthenticationApiResource {
@Consumes({ MediaType.APPLICATION_JSON })
@Produces({ MediaType.APPLICATION_JSON })
@Operation(summary = "Verify authentication", description = "Authenticates
the credentials provided and returns the set roles and permissions allowed.\n\n"
- + "Please visit this link for more info -
https://demo.fineract.dev/fineract-provider/legacy-docs/apiLive.htm#selfbasicauth";)
+ + "Please visit this link for more info -
https://fineract.apache.org/legacy-docs/apiLive.htm#selfbasicauth";)
@ApiResponses({
@ApiResponse(responseCode = "200", description = "OK", content =
@Content(schema = @Schema(implementation =
SelfAuthenticationApiResourceSwagger.PostSelfAuthenticationResponse.class))) })
public String authenticate(final String apiRequestBodyAsJson) {
diff --git
a/fineract-provider/src/main/java/org/apache/fineract/portfolio/self/security/api/SelfUserDetailsApiResource.java
b/fineract-provider/src/main/java/org/apache/fineract/portfolio/self/security/api/SelfUserDetailsApiResource.java
index dd893042d..79e431df4 100644
---
a/fineract-provider/src/main/java/org/apache/fineract/portfolio/self/security/api/SelfUserDetailsApiResource.java
+++
b/fineract-provider/src/main/java/org/apache/fineract/portfolio/self/security/api/SelfUserDetailsApiResource.java
@@ -52,7 +52,7 @@ public class SelfUserDetailsApiResource {
@GET
@Produces({ MediaType.APPLICATION_JSON })
@Operation(summary = "Fetch authenticated user details", description =
"Checks the Authentication and returns the set roles and permissions
allowed\n\n"
- + "For more info visit this link -
https://demo.fineract.dev/fineract-provider/legacy-docs/apiLive.htm#selfoauth";)
+ + "For more info visit this link -
https://fineract.apache.org/legacy-docs/apiLive.htm#selfoauth";)
@ApiResponses({
@ApiResponse(responseCode = "200", description = "OK", content =
@Content(schema = @Schema(implementation =
SelfUserDetailsApiResourceSwagger.GetSelfUserDetailsResponse.class))) })
public String fetchAuthenticatedUserData() {
diff --git
a/fineract-provider/src/test/java/org/apache/fineract/infrastructure/classpath/ClasspathDuplicatesStepDefinitions.java
b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/classpath/ClasspathDuplicatesStepDefinitions.java
index cdc2ca423..39e72fe41 100644
---
a/fineract-provider/src/test/java/org/apache/fineract/infrastructure/classpath/ClasspathDuplicatesStepDefinitions.java
+++
b/fineract-provider/src/test/java/org/apache/fineract/infrastructure/classpath/ClasspathDuplicatesStepDefinitions.java
@@ -35,10 +35,13 @@ public class ClasspathDuplicatesStepDefinitions implements
En {
private ClassGraph classGraph;
public ClasspathDuplicatesStepDefinitions() {
+ // tag::given[]
Given("A class graph", () -> {
this.classGraph = new ClassGraph();
});
+ // end::given[]
+ // tag::when[]
When("The user scans the class graph", () -> {
// nothing to do here
try (ScanResult scanResult = this.classGraph.scan()) {
@@ -61,12 +64,15 @@ public class ClasspathDuplicatesStepDefinitions implements
En {
}
}
});
+ // end::when[]
+ // tag::then[]
Then("There should be no duplicates", () -> {
if (!duplicates.isEmpty()) {
throw new AssertionFailedError(duplicates.size() + " Classpath
duplicates detected:\n" + duplicates);
}
});
+ // end::then[]
}
private boolean skipJAR(String jarPath) {
