Good catch, added HTTP_API_Component_Configuration.asciidoc to doclink file.

HTTP_API_Scripting.asciidoc

REST_API.asciidoc

are both in development guide. Also moved REST_API_Usage_Examples.asciidoc[] to development guide.

Changed some headings as well to make documentation flow better (i.e. no repeat headings)

Daniel Wisnewski wrote:

Good catch, added HTTP_API_Component_Configuration.asciidoc to doclink file.

Hmm, one problem with that -- why "doclink"? Why do we have two indexes (named index and @doclink@)? Maven is configured to use the former

<guide_filename>index</guide_filename>
…
<sourceDocumentName>${guide_filename}.asciidoc</sourceDocumentName>

I would remove one of the index files (and adjust maven configuration accordingly if needed).

As for developer guide - I would recommend keeping all component documentation (in dedicated component documentation - as for example in this case) together and split it only for the purpose of including in the complete server documentation (where we have separate admin and developer guide).

I've tried to bring the index files inline to documentation, however, because of the heading structure that the index files require (to build documentation on docs.tigase.org) they have to start at level zero (= heading). Even with specifying a leveloffset in the index.asciidoc, I can't quite get them to behave, and a lot of errors show during build. I tried this with the socks5 component, and while it works, it's kind of a mess.

The solution was to make a separate file, the doclink.asciidoc with the proper level offsets makes for a much cleaner build process.

It may be possible to set leveloffset for each component index.asciidoc file at 2, however as our documentation is written it ends up being something like this:

12.1 HTTP API

12.2 HTTP API Component

12.2.1 Common Module Configuration

12.2.1.1 Enabling/disabling module

12.2.1.2 Example

12.2.1.3 Context Path

...

It's not really optimal

The other reason for doclink was also to prevent separate component documentation so changes would only need one push (to component).

Alternatively, we could just use a single level 0 heading for component documentation, but it does not give a uniform flow to the documentation.

%wojtek What do you think would be best?

OK, so a little resume from our call:

• each chapter starts at "level 1" (i.e. headings at level "1" / with single "="):

• in index files there shouldn't be top leveloffset with an absolute level, index file heading should start with "level 1" / single "=" and then each chapter should be treated with relative @leveloffset@:

:leveloffset: +1

include::chapter01.adoc[]

include::chapter02.adoc[]

include::chapter03.adoc[]

:leveloffset: -1

include::chapter01.adoc[leveloffset=+1]

include::chapter02.adoc[leveloffset=+1]

include::chapter03.adoc[leveloffset=+1]

• in case of having both administrative and development guide:

  • create separate index_admin.asciidoc with list of administration / configuration chapters, create index_dev.asciidoc with list of development chapters (again, use relative offset as described above)

  • in the component documentation in the index.asciidoc include both index_admin.asciidoc and @index_dev.asciidoc@;

  • in the server link to index_admin.asciidoc and index_dev.asciidoc from Admin and Dev guide respectively.

With the relative leveloffsets this should be quite flexible and chapters should end up in the correct place depending from they are included.

(based on this: http://asciidoctor.org/docs/user-manual/#include-partitioning)

After considerable work, the documentation structure is re-written with the new in-line level offsets. Also included documentation headers and removed doclinks where not needed.

Looks great. As per our talk: please adjust paths of the imported documentation in server so they will be placed in target/ directory and update the import links.

everything builds okay in target directory now, back to you for QA

It looks great now! Thank you.