[JAMES-3187] fixes most documentation generation

[jeantil]

Generating the documentation raised lots of warnings and errors with dead links and missing attributes.

I did not fix the customization section ( 3 errors ) as I am unsure how to fix these links. The corresponding documentation lies in server specific directories.

I also changed some code blocks to have syntax highlighting and a more consistent syntax at least within a file.

[chibenwa]

Looks neat.

I bet now is about time to work on the overall content now that the form looks nicer...

[jeantil]

I bet now is about time to work on the overall content now that the form looks nicer...

The content is not so bad. I started building the documentation because I intended to find a place to write down what I learned about the BlobStore recently :d

From my pov, what's missing ( or the location is unclear or duplicated ) is

• reference documentation on the configuration files.
• how-tos

I'm a bit torn about the choice of using includes in the server's documentation. It makes it easier for users looking for a specific server's configuraton setup but it mostly duplicates content and makes linking to a specific configuration use case from other sections difficult (see customization for instance)

I noticed that the index of the configuration section for the basic server contained a lot of comments I haven't read it all yet, maybe that's where the reference configuration is supposed to live

[chibenwa]

I'm a bit torn about the choice of using includes in the server's documentation.

The idea was to avoid duplication and thus ensure easier maintenance and that the documentation stays relevant.

It allows to build a configuration tailor made per application addresses a major weakness of historical maven site that mixes everything and did never know if what he reads apply to him.

[jeantil]

I understand the idea of building tailored configuration per assembly, should we replicate this for the customization section then ?

[chibenwa]

Some extension mechanisms like mailbox listeners do not make sense for eg smtp only servers so I would say yes.