Convert documentation to Markdown

[weelink]

I was trying to find some documentation on Mapping by Code, but could not find anything useful except issue #1571. I'm thinking about contributing to this part of the documentation. However the current docs are in DocBook and need to be built using NAnt (that has not been updated in years).

How about converting the documentation to a more contributor-friendly format like Markdown? It will also make it easier to put the docs up on readthedocs.org.

[weelink]

Markdown is off the table if the documentation should be published on readthedocs.org. Their format of choice is reStructuredText and convert it using Spinx.

If that is going to be the direction of the docs, then the docbook should be converted to reStructuredText (pretty easy using Pandoc and the build script for the documentation should be modified to use Sphinx. Haven't looked at that yet.

[weelink]

The reason to convert the documentation to Markdown was the ease of maintenance (tool support), ease of generation (no more xml/xsl/nant/java etc), and to allow the docs to be found through the newer channels (notably readthedocs.io and/or github). Since Markdown has its limits, I have converted it to reStructuredText.

I have managed to let TeamCity build the documentation using reStructuredText.
In order to make this happen, I had to include a zipped version Python as part of the Tools. This is 30MB.
There are still a few things to do, namely fixing some formatting issues with the PDF and HTML, and I accidentally broke the generation of the API documentation (so the build fails at the moment).
It will take some time before this is fixed.

When I look at the download statistics in SourceForge, it seems that practically no one is actually downloading the releases and even less people download the documentation. NuGet and http://nhibernate.info/ seem to be the most used option.
So I was wondering if I should continue my attempt at generating the documentation in TeamCity.

There are some options to consider:

1. Close this issue and keep the documentation in DocBook
2. Keep the documentation in reStructuredText, accept the Python bloat, fix the build and let it be published to SourceForge
3. Stop generating the documentation as part of the release, and only publish it on readthedocs.io/github/whatever

Every option has its pros and cons. It is beyond my power as a contributor to make a decision.
Can some of the owners (@fredericDelaporte, @hazzik, @someone_else) of NHibernate think about this?

[hazzik]

I would personally prefer option 1.

[fredericDelaporte]

I accidentally broke the generation of the API documentation (so the build fails at the moment)

If by API documentation, you mean documentation built from xml comment, it is not currently built by TeamCity. What I see failing in TeamCity is the conversion of the reference documentation (the one currently made with DocBook) to the CHM format.

So I was wondering if I should continue my attempt at generating the documentation in TeamCity.

This is what is used for updating nhibernate.info (which is a github site), so it has to work, unless the documentation hosting is entirely moved to readthedoc.

As for the options, I also prefer 1 for now.

Granted, DocBook looks fossilized, but it does the job, allows to test locally the generated doc, while not having a steep learning curve. The main drawback of the current documentation is that it needs manual operations for updating nhibernate.info and versioning it. But these are not very time consuming, especially since there are not very frequent updates of the documentation.

[weelink]

Option 1 is the safest and, at the moment, the only working one.
Maybe sometime in the future there will be easier/better ways to do the documentation, but for now I'll close this issue and the related PR.