Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

238 lines (184 sloc) 7.07 KB

Demo PzdcDoc

Full reference of AsciiDoctor syntax is available here: https://asciidoctor.org/docs/user-manual

Second level header

Reference of selected blocks: https://asciidoctor.org/docs/user-manual/#style

Note
Note.
Warning
Warning.
Caution
Take attention.
Important
It is important.
Important

This is very important block.

Contains list items:

  • One.

  • Two.

List:

  • Position 1

  • Position 2

Third level header, description list

CPU

Sometimes is needed for PC.

RAM

Is also needed.

Tables

Simple example

Service / Component

Converter Service

Index and Search Service

Sample with joined cells

Key Description

indexer.context.sharepoint.url

Root URL of SharePoint site.
Sample: https://sp.mycompany.i
Sample Cloud: https://mycompany.sharepoint.com

indexer.context.sharepoint.url.preprocess

JS function for modifying URL before every request

Sample: Requesting SP on different port.

indexer.context.sharepoint.request.url.preprocess:
    new Funct({process : function(url) {
      return url.replace("http://sp.mycompany.i", " https://sp.mycompany.i:555");
   }})

indexer.context.sharepoint.user

SharePoint access user.
Sample: myuser
Sample Cloud: myuser@mycompany.com

Code snippets

Extracted "live snippets"

The source link below is automatically extracted to highlighted code snippet during HTML convertion. Attributes from and to allow check actuality of content, remove-leading - deletion of line indent. Here is the snippet of connecting plugins to DocGenerator.

Simple snippets

Configuration or another selected block of code (source adds horisontal scrolling if needed):

# при ошибке правки параметров - обновление таблицы с параметрами, необходимо в случае, если при этом другие параметры изменяются динамическим кодом
onErrorChangeParamsReload=1
# код параметра - категории, который должен быть указан перед переводом процесса в конечный статус
categoryParamId=<param_code>
# требование заполненности параметров перед установкой статуса, одна или несколько записей вида
requireFillParamIdsBeforeStatusSet.<status_to_code>=<param_codes>

Java code:

class My {
   private int a;

   public My() {
   		a = 5;
   }
}

References

Resources

Image, recommended to be places in directory _res near of the file.

image

Big images may be restricted by width, recommended 600px for horizontal oriented и 300 vertical:

image

Any file from a project may be also referenced and automatically copied to _res subdirectory.

Content of class org.pzdcdoc.Snippet

JavaDoc

Link to JavaDoc of the class: javadoc:ru.bgcrm.dao.user.UserDAO[]

Cross documents

References to .adoc files being converted to .html links and validated to corectness.

Another document: Module

Chapter in the current document: Snippets

Chapter in another document: About

Use such links for referencing on not ready parts TODO, they may be easily found later.

Such link causes a validation error, may be used for marking not finished places:

<<todo, todo>>

Selections

For any selection except of links use bold font: variable, path, parameter, interface ⇒ menu ⇒ item

Diagrams

Embedded

Supported Ditaa and PlantUML diagrams.

Advantages:

  • lightness;

  • quick preview;

  • simplicity and uniformity;

  • storage and editing in the text of the document;

  • no need to export.

Ditaa

Ditaa is a ASCII-based format of block diagrams. Here is the original page: http://ditaa.sourceforge.net/ and actual repo: https://github.com/stathissideris/ditaa

References:

+------------------+       +---------------+
|                  |       |               |
|  Test for Adoc   +------>+   Diagrams    |
|                  |       |               |
+------------------+       +---------------+

And a complex sample.

                /-----------\
           /--->+  context  |
           |    \------+----/
  all jobs |           |       knows root job                  points to super job
  point to |     seeds |   /-----------------------------+------------------------------\
   context |           |   |                             :                              |
           |           v   v     splits/merges           v         splits/merges        |
           :    +------+---+--+     starts       +-------+-------+      starts    +------+------+
           \----+ (root) job  +----------------->+ sub/super job +--------------->|   sub job   |
                +------+---+--+                  +-------+-------+                +------+------+
                       |   ^                             :                              ^
               creates |   :                             |                              |
                       |   | know each other             \------------------------------/
      starts on change |   | (parent <-> child)                 points to sub job
                       v   v
                +------+---+--+
                |  child job  |
                +-------------+

With 3rd party editors

Schemas can also be produced using third-party editors, for example: yEd Source files are stored in _res directories under names ending in _schema.graphml. Files have to be exported as images in PNG format, preferably with the same name. After any change source files have to be re-exported.

Tools

AsciiDoctor may be edited in any text editor, but as more comfortable way I use an Eclipse plugin.

eclipse plugin

Features:

  • structure preview in Outline section;

  • hot keys like Ctrl + b for typical formatting options.

Preview I normally do not use, just do generation and refresh in the running browser.

You can’t perform that action at this time.