You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fineract.apache.org by al...@apache.org on 2022/05/10 10:13:05 UTC
[fineract] branch develop updated: FINERACT-1608: Add introduction to Asciidoc
This is an automated email from the ASF dual-hosted git repository.
aleks pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/fineract.git
The following commit(s) were added to refs/heads/develop by this push:
new b0a261cbd FINERACT-1608: Add introduction to Asciidoc
b0a261cbd is described below
commit b0a261cbd5389bf02a7ba42a56ab3bf004dc931e
Author: Aleks <al...@apache.org>
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: 'dev@fineract.apache.org',
+ 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:dev@fineract.apache.org[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 dev@fineract.apache.org. 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 announce@apache.org (sender address must be @apache.org):
+Send an email to `announce@apache.org` (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: dev@fineract.apache.org
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) {