I prepared AsciiDoc based documentation for this project. As I tested it works ok.

%wojtek Could you check if configuration is ok? Do we need to do anything else before adding this documentation to docs.tigase.org? Documentation is only in master branch and for 7.2.0, but do we need to adjust jenkins? If so, then can we do this now or we need to wait?

It would be good if someone else would review this documentation and check if everything is clear. However before that I think we would need to wait for documentation for new DSL format as documentation for HTTP API already contains references to DSL format.

Andrzej Wójcik wrote:

I prepared AsciiDoc based documentation for this project. As I tested it works ok.

%wojtek Could you check if configuration is ok? Do we need to do anything else before adding this documentation to docs.tigase.org?

I've checked it and corrected a couple of things (added missing css file and images directory - currently required for chunked html); I've also included configuration for including javadocs, but there are compilation errors (*) so I wasn't able to test it.

Documentation is only in master branch and for 7.2.0, but do we need to adjust jenkins? If so, then can we do this now or we need to wait?

It would be good if someone else would review this documentation and check if everything is clear. However before that I think we would need to wait for documentation for new DSL format as documentation for HTTP API already contains references to DSL format.

Given that it contains references to new Tigase format (which is not yet published, as current 'snapshot' references origin/release branch, i.e. 7.1.0) I would say we could, until release of 7.1.0, leave it as is without publishing it to docs.tigase.org.

I'll review it later on and/or - %daniel - could you check it for language correctness?

(*) %andrzej.wojcik compilation errors - for example:

[INFO] --- maven-compiler-plugin:3.2:compile (default-compile) @ tigase-http-api ---
[INFO] Changes detected - recompiling the module!
[INFO] Using Groovy-Eclipse compiler to compile both Java and Groovy files
[INFO] -------------------------------------------------------------
[ERROR] COMPILATION ERROR :
[INFO] -------------------------------------------------------------
[ERROR] /Users/wojtek/dev/tigase/tigase-http-api/src/main/groovy/tigase/http/modules/IndexModule.java:[44,23] 1. ERROR in /Users/wojtek/dev/tigase/tigase-http-api/src/main/groovy/tigase/http/modules/IndexModule.java (at line 44)
	@Bean(name = "index", parent = HttpMessageReceiver.class)
	                      ^^^^^^
The attribute parent is undefined for the annotation type Bean

[ERROR] /Users/wojtek/dev/tigase/tigase-http-api/src/main/groovy/tigase/http/modules/IndexModule.java:[45,14] 2. ERROR in /Users/wojtek/dev/tigase/tigase-http-api/src/main/groovy/tigase/http/modules/IndexModule.java (at line 45)
	public class IndexModule extends AbstractModule {
	             ^^^^^^^^^^^
The hierarchy of the type IndexModule is inconsistent

[ERROR] /Users/wojtek/dev/tigase/tigase-http-api/src/main/groovy/tigase/http/upload/db/FileUploadRepository.java:[24,8] 3. ERROR in /Users/wojtek/dev/tigase/tigase-http-api/src/main/groovy/tigase/http/upload/db/FileUploadRepository.java (at line 24)
	import tigase.db.DataSource;
	       ^^^^^^^^^^^^^^^^^^^^
The import tigase.db.DataSource cannot be resolved

…

This compilation errors are caused by the fact that in our Maven snapshot repository there is no current build of Tigase XMPP Server from master branch which would include this changes. Due to that maven most likely used some old snapshot build of version 7.2.0 from your local repository or from our snapshot repository. Using fresh build of Tigase XMPP Server from master branch I do not get any compilation issues.

IMHO even more reason to align finishing this task with 7.1.0 release - agreed?

Agreed

%wojtek Please forward ticket to me once compilation errors are fixed, I will look over documentation.

Andrzej Wójcik wrote:

It would be good if someone else would review this documentation and check if everything is clear.

%andrzej.wojcik - some comments:

• Enabling/disabling module - I would list available modules; // later comment - ok, modules are listed as headers - I think moving it one-level-down and/or grouping under Available modules could be helpful/make things more readable;

• 2.1.3. List of virtual hosts (and potentially others) - if this is multiple item configuration, information how to enter multiple items would be helpful (do we requires quotes, is it comma or semicolon separated?)

• Admin UI module -- I'm not sure whether we should point it to the other guide explaining this module or move the documentation to this guide -- comments?

• 2.7. Setup module point to the guide describing setup?

• enabling HTTP File Upload component in DSL format looks/feels weird - does it utilize defaults to @true@?

• _ JDBCFileUploadRepository_ -- should we load this schema in installer? include information about loading particular schema files in documentation? we cover this for pubsub and others...

• Complex configuration example -- it lacks configuration example for old format - is it supported?

• Executing example ad-hoc command / using XML - there are pre tags left from redmine;

For now I've manually build the doc and put it on docs.tigase.org -- http://docs.tigase.org/#collapse-tigase-jaxmpp-snapshot-head

%daniel -- I've made a Tigase 7.2.0 build, deployed it to maven repo so now you can build tigase-http-api component.

Wojciech Kapcia wrote:

Andrzej Wójcik wrote:

It would be good if someone else would review this documentation and check if everything is clear.

%andrzej.wojcik - some comments:

• Enabling/disabling module - I would list available modules; // later comment - ok, modules are listed as headers - I think moving it one-level-down and/or grouping under Available modules could be helpful/make things more readable;

I agree. I initially listed this modules at this level to include them in table of content and to not include other more important things at similar level.

• 2.1.3. List of virtual hosts (and potentially others) - if this is multiple item configuration, information how to enter multiple items would be helpful (do we requires quotes, is it comma or semicolon separated?)

In case of properties file it is comma separated list and in case of DSL it is a list of strings like: [ 'api.example.com', 'rest.example.com' ] and example for this is in section Complex example few lines below, but I suppose I could extend original example in VHost section.

• Admin UI module -- I'm not sure whether we should point it to the other guide explaining this module or move the documentation to this guide -- comments?

Do we have other guide for this module? Is so that we should point to it or include it.

• 2.7. Setup module point to the guide describing setup?

Then we should point to this guide. I needed to add simple information about this module, so reader would know that it exists and what it does, so linking to other guide is a good idea.

• enabling HTTP File Upload component in DSL format looks/feels weird - does it utilize defaults to @true@?

Yes, beans () deafults value of active to true - this is why I want to create documentation for this DSL format and add it to Tigase XMPP Server documentation.

• _ JDBCFileUploadRepository_ -- should we load this schema in installer? include information about loading particular schema files in documentation? we cover this for pubsub and others...

Good catch, we need to extend installer to make it possible to configure this module and prepare database for it as well.

• Complex configuration example -- it lacks configuration example for old format - is it supported?

Yes, it is supported. I will add it today.

• Executing example ad-hoc command / using XML - there are pre tags left from redmine;

I will remove them while I will work on other comments.

For now I've manually build the doc and put it on docs.tigase.org -- http://docs.tigase.org/#collapse-tigase-jaxmpp-snapshot-head

%daniel -- I've made a Tigase 7.2.0 build, deployed it to maven repo so now you can build tigase-http-api component.

%andrzej.wojcik

Andrzej Wójcik wrote:

Wojciech Kapcia wrote:

• 2.1.3. List of virtual hosts (and potentially others) - if this is multiple item configuration, information how to enter multiple items would be helpful (do we requires quotes, is it comma or semicolon separated?)

In case of properties file it is comma separated list and in case of DSL it is a list of strings like: [ 'api.example.com', 'rest.example.com' ] and example for this is in section Complex example few lines below, but I suppose I could extend original example in VHost section.

I'm more in favour of explicitly stating what is required. For example our properties guide:

http://docs.tigase.org/tigase-server/7.0.3/Properties_Guide/html_chunk/virtHosts.html

Possible values: comma separated list of domains.

• Admin UI module -- I'm not sure whether we should point it to the other guide explaining this module or move the documentation to this guide -- comments?

Do we have other guide for this module? Is so that we should point to it or include it.

We do: http://docs.tigase.org/tigase-server/snapshot/Administration_Guide/html/#adminUI

My suggestion - at first link to this guide, and after we figure out including per-component-guides then we can move the whole section from AdminGuide to HTTP-API guide (would also help with slimming down huge Admin guide, which takes long to build).

Same goes for WebUI/jaxmpp Client -- http://docs.tigase.org/tigase-server/snapshot/Administration_Guide/html/#webClient

• 2.7. Setup module point to the guide describing setup?

Then we should point to this guide. I needed to add simple information about this module, so reader would know that it exists and what it does, so linking to other guide is a good idea.

http://docs.tigase.org/tigase-server/snapshot/Administration_Guide/html/#webinstall

One problem I can see now is linking between guides. Probably only information that the setup is described in Admin guide > secion x.y.z could be made.

• enabling HTTP File Upload component in DSL format looks/feels weird - does it utilize defaults to @true@?

Yes, beans () deafults value of active to true - this is why I want to create documentation for this DSL format and add it to Tigase XMPP Server documentation.

definitely +1 ;)

%wojtek If you have and idea how to better describe vhosts list property then please change it.

I've made changes and cleanup to documentation for editing and readability. Also i've changed JSON source type to JAVA as JSON kept returning odd formatting and distracting colors.

We can port this documentation over to admin_guide and strip DSL style configuration and HTTP upload for v7.1.0 version if needed. andrzej let me know if you would like me to do that.

As far as cross referencing other documents, i've used http://docs.tigase.org/tigase-server/snapshot/Administration_Guide/html/# for the links.

We've never found a way to properly cross reference documents using our build and asciidoc as each project seems to be totally separate and attempts to link them have not resulted in any positive results.

The best way I can see (short of changing our documentation format and build procedure) is to combine all different documents into a single document, while massive, could have seperate parts for modules/components etc.. This can allow for consistent cross references in all documents.

Thank you for a review and corrections.

As for I do not recommend to port this to 7.1.0 as some property names changes in version scheduled to be released with 7.2.0. Also some new options were added or configuraion format was changed.

In 7.2.0 I prepared functionality which during Tigase Server startup will convert old properties based file format into DSL based and store it as @etc/init.properties.new@.

Due to that I have mixed fillings about one change you did. As you used following phrases "Configuration in DSL type file" and "Configuration in init.properties file", while in fact configuration in DSL format may be stored in file name init.properties (I even use it this way right now). So this phrases can be misleading.

As for linking documentation, I think we need to deal with it somehow. I think that each project should have separate documentation as this way it is easy to add something to project documentation when I implement new feature. Having documentation only in Tigase XMPP Server forces us to update this repository as well - not a good idea.

I think that we could try to create documentation for every module and during compilation of Tigase XMPP Server merge it somehow. Or maybe for that merged documentation we should create separate project? It would just retrieve sources, merge documentation in asciidoc and generate merged documentation?

Other solution would be to pass variable from Maven to AsciiDoctor and use this variable to create link. In this variable or variables we could have current version of project and dependencies being build, which should allow us to generate link to proper documentation files.

If not that we should point to Tigase documentation page and just give name of documentation to look for.

I've changed the wording to "Configuration in old properties file:" for now to differentiate things.

As for combining documentation, I'm going to create another ticket for this. Andrzej, if you are satisfied close this ticket to move the project forward.

Andrzej Wójcik wrote:

As for linking documentation, I think we need to deal with it somehow. I think that each project should have separate documentation as this way it is easy to add something to project documentation when I implement new feature. Having documentation only in Tigase XMPP Server forces us to update this repository as well - not a good idea.

+1 for documenting each project in it's own repository - this way we have documentation tied to particular sourcecode and it makes managing it way easier.

I think that we could try to create documentation for every module and during compilation of Tigase XMPP Server merge it somehow. Or maybe for that merged documentation we should create separate project? It would just retrieve sources, merge documentation in asciidoc and generate merged documentation?

Other solution would be to pass variable from Maven to AsciiDoctor and use this variable to create link. In this variable or variables we could have current version of project and dependencies being build, which should allow us to generate link to proper documentation files.

What do you mean "merged documentation"?

Please keep in mind, that we can't simply have "link in variable" as we have documentation in various formats and they have different ways to manage inter-document/inter-section linking (PDF being most different).

At the beginning I was thinking of simply including per-component documentation in separate jar and then using it as dependency to extract it and place in @tigase-server/docs/@, next to existing AdminGuide and others (and we are doing something similar for database schemas already).

Possibly we could later on employ similar method in the mentioned separate project, which would be basically a global index file with the list of all guides to be included, but this could possibly break in other ways, especially in terms of paths to non-asciidoc files. %daniel - you were experimenting with similar setups -- do you think it could work? Asciidoc linking is based mostly on section IDs, so in principle creating new uber-index with include::AdminGuide, include::HTTPAPI_Guide could work?

If not that we should point to Tigase documentation page and just give name of documentation to look for.

For now I think this is the simplest approach.

I agree with %wojtek

For now I'm closing this task.

For some unknown reason I'm not able to close this task.

"relations of your issues. You can't close an issue that is blocked by another one."

While I was testing other task (#4727) I ran into a couple of problems and starting HTTP component was a bit difficult - when trying to find answers in the documentation I found myself a bit stumped, hence a couple of additional comments:

HTTP server instance is provided as httpServer by default.

how? Where should it be put?

using

httpServer {}

or complete example from one of the sections below

httpServer {
    connections {
        8443 () {
            socket = ssl
            domain = 'example.com'
        }
    }
}

does nothing.

Then I moved to enabling http component (what's the relation? how the configuration be arranged - level wise? my assumption is that server and port configuration should be done within context of the component, or the particular module as previously it had following configuration @http/http/server-class…@) - I had to explicitly use class:

http (class: tigase.http.HttpMessageReceiver) {}

and while it's not a problem - documentation doesn't mention it in any place and examples doesn't use it, even complete example:

http {
    index (active: false) {}
    rest {
        context-path = '/'
        vhosts = [ 'api.example.com', 'rest.example.com' ]
    }
}

I think it would be good to include complete and verbose configuration with various options in one place.

Wojciech Kapcia wrote:

While I was testing other task (#4727) I ran into a couple of problems and starting HTTP component was a bit difficult - when trying to find answers in the documentation I found myself a bit stumped, hence a couple of additional comments:

HTTP server instance is provided as httpServer by default.

how? Where should it be put?

HTTP server bean is registered automatically as @httpServer@. No need to put anything!

This HTTP server will be started only if there is at least one other module which requires it (ie. HttpMessageReceiver or @FileUploadComponent@)

using

[...]

or complete example from one of the sections below

[...]

does nothing.

It configures server, but as I mentioned above - server is not started if there is no bean which needs this HTTP server.

Then I moved to enabling http component (what's the relation? how the configuration be arranged - level wise? my assumption is that server and port configuration should be done within context of the component, or the particular module as previously it had following configuration @http/http/server-class…@) - I had to explicitly use class:

[...]

and while it's not a problem - documentation doesn't mention it in any place and examples doesn't use it, even complete example:

[...]

I think it would be good to include complete and verbose configuration with various options in one place.

HTTP server is no longer used by only one component and due to that it is configured as a separate bean (now we have HttpMessageReceiver and FileUploadComponent). If we would configure HTTP server on component level then it would not be possible to host FileUploadComponent and HttpMessageReceiver on same HTTP server and on same port.

Your initial configuration of httpServer actually configured component, but it was not needed - so it was not started!

Here is example configuration of @httpServer@:

• listen only on port @8081@:

httpServer () {
    connections {
        8080 (active: false) {}
        8081 () {}
    }
}

• using Jetty HTTP Server:

httpServer (class: tigase.http.jetty.JettyStandaloneHttpServer) {
     connections {
        8080(active: false) {}
        8081() {
            socket = ssl
        }
    }
}

• adding HTTPS on port 8443 (still listen for HTTP on @8080@):

httpServer {
    connections {
        8443 () {
            socket = ssl
            domain = 'example.com'
        }
    }
}

For now every module and component is available on every port. Later on we may provide additional option component/module to make them available only on particular port of HTTP Server (if HTTP server will be configured to listen on this ports)

OK, this is how it works now.

%wojtek Do you have any suggestions how to modify documentation?

As per our discussion:

• it doesn't work for me - lack of parenthesis and as a result - component being inactive (please make it more clear in DSL documentation)

• also - we should have a log entry that even though we have a component configuration it's not loaded.

• please also review all examples.

I added additional warning in DSL documentation about meaning of parenthesis. I hope now it is more clear.

Moreover I added log entry with CONFIG level to inform user if this situation happens again.

However this issue was not caused by misconfiguration but by use of incorrect version of dependencies during creation of distribution archive. I reviewed all dependecies and update them if needed.

As for not using trusted property set in component level, I was not able to replicate it. I think it maybe somehow related to incorrect dependecies versions. I would like to suggest to clean projects and rebuild them.

OK, latest version and examples works. Having a better grasp over internals I would like to propose:

• moving REST API section under 2.5. REST module instead of having it on the same level as HTTP-API and Upload components

• given that current docs (from @origin/master@) are mostly intended for 7.2.0 I would remove legacy configuration and leave only DSL one.

Small update - even without any configuration http-api component is being loaded (and there is no mention about it! I've already commented about it in other ticket). While making it easier to define default components (instead of array in @Configurator@) I'm not sure that http-api should be enabled by default (except for setup purposes), especially considering: Instance of HTTP server is by default provided under name of httpServer. It will be enabled only if HTTP API component will be active of if HTTP File Upload component will be available. (also: it's worded a bit weird IMHO).

Wojciech Kapcia wrote:

OK, latest version and examples works. Having a better grasp over internals I would like to propose:

• moving REST API section under 2.5. REST module instead of having it on the same level as HTTP-API and Upload components

I' not sure that we should move it there as it will not be visible in a table of content and will make it harder to find. Also REST API section is more important to developers or users while 2.5. REST module section is rather for system administrators.

I think that maybe we should leave it as it is and %daniel while he will be cleaning up documentation will decide where to put this section.

• given that current docs (from @origin/master@) are mostly intended for 7.2.0 I would remove legacy configuration and leave only DSL one.

I agree. Documentation was created when we weren't 100% sure that DSL will be the only way to configure 7.2.0 so I've created samples in both formats, but now properties based configuration examples will only cause confusion. I'm removing them.

As for automatic loading of HTTP component - we are already discussing it in separate task related to automatic load of components.

Andrzej Wójcik wrote:

Wojciech Kapcia wrote:

OK, latest version and examples works. Having a better grasp over internals I would like to propose:

• moving REST API section under 2.5. REST module instead of having it on the same level as HTTP-API and Upload components

I' not sure that we should move it there as it will not be visible in a table of content and will make it harder to find.

You can set the ToC Level: http://asciidoctor.org/docs/user-manual/#user-toc-levels

Also REST API section is more important to developers or users while 2.5. REST module section is rather for system administrators.

Make two main sections: User Guide / Dev guide and move the items accordingly? However it feels that the mentioned section would be a better fit in the UberGuide of the server in the DeveloperGuide (should be possible to include it there)

I think that maybe we should leave it as it is and %daniel while he will be cleaning up documentation will decide where to put this section.

It's always good to bounce ideas off :-)

Wojciech Kapcia wrote:

Andrzej Wójcik wrote:

Wojciech Kapcia wrote:

OK, latest version and examples works. Having a better grasp over internals I would like to propose:

• moving REST API section under 2.5. REST module instead of having it on the same level as HTTP-API and Upload components

I' not sure that we should move it there as it will not be visible in a table of content and will make it harder to find.

You can set the ToC Level: http://asciidoctor.org/docs/user-manual/#user-toc-levels

Yes, I know but in my opinion it better fits where it already is.

Also REST API section is more important to developers or users while 2.5. REST module section is rather for system administrators.

Make two main sections: User Guide / Dev guide and move the items accordingly? However it feels that the mentioned section would be a better fit in the UberGuide of the server in the DeveloperGuide (should be possible to include it there)

It could be done, but if I would work on integration with Tigase XMPP Server I would look into user guide for description of REST API as I'm not developing a server component. But maybe I'm wrong about that.

Also I do not like idea of spitting it into 2 sections.

I think that maybe we should leave it as it is and %daniel while he will be cleaning up documentation will decide where to put this section.

It's always good to bounce ideas off :-)

I think that we should wait for %daniel and his opinion on this as all our documetations should be coherent in layout, format, etc.

Andrzej Wójcik wrote:

Also REST API section is more important to developers or users while 2.5. REST module section is rather for system administrators.

Make two main sections: User Guide / Dev guide and move the items accordingly? However it feels that the mentioned section would be a better fit in the UberGuide of the server in the DeveloperGuide (should be possible to include it there)

It could be done, but if I would work on integration with Tigase XMPP Server I would look into user guide for description of REST API as I'm not developing a server component. But maybe I'm wrong about that.

%andrzej.wojcik

IMHO "Development Guide" doesn't mean it's only about developing Tigase code - it would merely mean it consist all informations for the developers.

Also I do not like idea of spitting it into 2 sections.

Not splitting - only linking differently. For docs.tigase.org we would have a single http-api documentation; in tigase-server REST API part could be linked in the developer-guide.

I guess question for %kobit as he mentioned a while back that he wants DevGuide separately.

I think that maybe we should leave it as it is and %daniel while he will be cleaning up documentation will decide where to put this section.

It's always good to bounce ideas off :-)

I think that we should wait for %daniel and his opinion on this as all our documetations should be coherent in layout, format, etc.

Assigning to Dan then.

I wrestled with this one for a while, but i've split up the documentation into both Admin and Developers guide to what I think is appropriate. The only downside to my method is some duplicates inside the build directories unless we make discrete directories for Dev and User.

%wojtek Do you think we should separate component documentation into dev and user directories? This could cut down on extra files and make it simpler for us to determine what documents go where.

Daniel Wisnewski wrote:

I wrestled with this one for a while, but i've split up the documentation into both Admin and Developers guide to what I think is appropriate. The only downside to my method is some duplicates inside the build directories unless we make discrete directories for Dev and User.

It seems it broke the build: http://build.tigase.org/jenkins/job/tigase-server-distribution/1146/tigase$tigase-server-docs-devel/console (#4956).

What duplicates are you talking about? I've quickly looked at the changes and haven't noticed duplicates.

wojtek Do you think we should separate component documentation into dev and user directories? This could cut down on extra files and make it simpler for us to determine what documents go where.

If my understanding is correct you are talking about temporary, work/build directory with extracted contents from other components? But this doesn't matter as this is only a temporary and it will not result in duplication in in sources - correct?

Wojciech Kapcia wrote:

If my understanding is correct you are talking about temporary, work/build directory with extracted contents from other components? But this doesn't matter as this is only a temporary and it will not result in duplication in in sources - correct?

Yes, just a temporary directory during the build. Associated breaks in the build have been fixed.

HTTP_API_Component_modules and

REST_API has been added to devguide

HTTP_API_Component

HTTP-Server

HTTP_File_Upload_Component

Have been added to adminguide.

Please check to see if this makes sense to you Andrzej.

In my opinion we have two issues here:

1. I think we need HTTP_API_Component_modules in admin guide - not in devguide as there is a description how to configure every module with module specific settings - this is something which administrator would do.

2. In your recent change, you removed HTTP_API_Component_module from HTTP API documentation (https://projects.tigase.org/projects/tigase-http-api/repository/revisions/5098ff450040c1d068773eededeaeab389d7dd87/diff/src/main/asciidoc/text/HTTP_API_Component.asciidoc). While it is still available in aggregated version of Tigase XMPP Server documentation it is lost form Tigase HTTP API Component documentation.

%wojtek What do you think?

I pulled the link from HTTP_Component_Module and kept it in index.asciidoc since I had split that document. I will move component_module documentation back to Admin Guide.

For me, it's much easier to keep track of documentation if all new /text files are in index.asciidoc in case they need to be re-arranged.

I am thinking, would it be common to have separate documentation for many components or other plugins between devguide and admin guide? If this is the case we can structure the documentation like:

HTTP_Docs

../Dev

../../index.asciidoc

../Admin

../../index.asciidoc

And then just include the indexes as appropriate like we do now.

Andrzej Wójcik wrote:

In my opinion we have two issues here:

I think we need HTTP_API_Component_modules in admin guide - not in devguide as there is a description how to configure every module with module specific settings - this is something which administrator would do.

In your recent change, you removed HTTP_API_Component_module from HTTP API documentation (https://projects.tigase.org/projects/tigase-http-api/repository/revisions/5098ff450040c1d068773eededeaeab389d7dd87/diff/src/main/asciidoc/text/HTTP_API_Component.asciidoc). While it is still available in aggregated version of Tigase XMPP Server documentation it is lost form Tigase HTTP API Component documentation.

wojtek What do you think?

Yes, that was the initial idea. All of HTTP-API would go into Admin Guide, and only small part, related to development (so, REST api) would be included in Development Guide.

I'm aware it could be a bit tricky as it would require linking to particular documents in the index in Tigase Server.

Possibly it could be solved by only doing it in DevGuide (and linking to whole HTTP-API guide in Admin Guide)

Daniel Wisnewski wrote:

I pulled the link from HTTP_Component_Module and kept it in index.asciidoc since I had split that document. I will move component_module documentation back to Admin Guide.

For me, it's much easier to keep track of documentation if all new /text files are in index.asciidoc in case they need to be re-arranged.

I think structure / order devised in the component guide is good, so the effort is to take complete chunks and place them in correct location.

I am thinking, would it be common to have separate documentation for many components or other plugins between devguide and admin guide? If this is the case we can structure the documentation like:

HTTP_Docs

../Dev

../../index.asciidoc

../Admin

../../index.asciidoc

And then just include the indexes as appropriate like we do now.

Yes, it's quite possible (for example pubsub also has REST API and it could go to Dev Guide, by the same principles as discussed above). But this doesn't necesserily mean you need to sort and order documents on where they are in the guide - that's the purposed and beauty of asciidoc and lining that you can re-order the chapters by simply changing one file (index) without renaming whole directories/files (which only makes it more difficult to track in repository).

And what's more - basic component configuration need to contain all chapters in single document.

I think we can close this issue, current documentation structure is simpler and works OK.