Add doc cmake targets (HTML, PDF, QtHelp, CHM, man)

make doc will build all of the above, except for CHM,
which needs manual preparation and can be built with
make doc-chm. See doc/scripts/README.rst for details.

We do our best to ensure to detect the required tools
before adding targets, so a build should always succeed.

Exception: On Debian and Ubuntu, the following packages are
required to build the PDF target (in addition to pdflatex
itself, which is autodetected):

* texlive-latex-recommended
* texlive-latex-extra
* texlive-fonts-recommended

If pdflatex is present, but those are not, the doc target
will fail.

Results can be found in $BUILDDIR/doc/$format.

CMakeLists.txt

@@ -40,6 +40,8 @@ endif()
 find_package(Qt4 4.6.0 COMPONENTS QtCore QtGui QtXml QtNetwork QtTest REQUIRED )
 find_package(Csync)
 find_package(INotify)
+find_package(Sphinx)
+find_package(PdfLatex)
 
 set(WITH_CSYNC CSYNC_FOUND)
 set(USE_INOTIFY ${INOTIFY_FOUND})
@@ -81,6 +83,8 @@ file( GLOB TRANS_FILES ${CMAKE_SOURCE_DIR}/translations/mirall_*.ts)
 set(TRANSLATIONS ${TRANS_FILES})
 
 add_subdirectory(src)
+add_subdirectory(doc)
+
 if(UNIT_TESTING)
     include(CTest)
     enable_testing()
@@ -92,4 +96,3 @@ if(BUILD_OWNCLOUD_OSX_BUNDLE)
 else()
     install( FILES sync-exclude.lst DESTINATION ${CMAKE_INSTALL_SYSCONFDIR} )
 endif()
-

cmake/modules/FindPdfLatex.cmake

@@ -0,0 +1,16 @@
+find_program(PDFLATEX_EXECUTABLE NAMES pdflatex
+  HINTS
+  $ENV{PDFLATEX_DIR}
+  PATH_SUFFIXES bin
+  DOC "PDF LaTeX"
+)
+
+include(FindPackageHandleStandardArgs)
+
+find_package_handle_standard_args(PdfLatex DEFAULT_MSG
+  PDFLATEX_EXECUTABLE
+)
+
+mark_as_advanced(
+  PDFLATEX_EXECUTABLE
+)

cmake/modules/FindSphinx.cmake

@@ -0,0 +1,16 @@
+find_program(SPHINX_EXECUTABLE NAMES sphinx-build
+  HINTS
+  $ENV{SPHINX_DIR}
+  PATH_SUFFIXES bin
+  DOC "Sphinx documentation generator"
+)
+
+include(FindPackageHandleStandardArgs)
+
+find_package_handle_standard_args(Sphinx DEFAULT_MSG
+  SPHINX_EXECUTABLE
+)
+
+mark_as_advanced(
+  SPHINX_EXECUTABLE
+)

doc/CMakeLists.txt

@@ -0,0 +1,61 @@
+if(SPHINX_FOUND)
+
+    # Sphinx cache with pickled ReST documents
+    set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
+    # HTML output directory
+    set(SPHINX_HTML_DIR     "${CMAKE_CURRENT_BINARY_DIR}/html")
+    set(SPHINX_MAN_DIR      "${CMAKE_CURRENT_BINARY_DIR}/man")
+    set(SPHINX_PDF_DIR      "${CMAKE_CURRENT_BINARY_DIR}/latex")
+    set(SPHINX_QCH_DIR      "${CMAKE_CURRENT_BINARY_DIR}/qthelp")
+    set(SPHINX_HTMLHELP_DIR "${CMAKE_CURRENT_BINARY_DIR}/htmlhelp")
+    set(MSHTML_COMPILER     wine 'C:\\Program Files\\HTML Help Workshop\\hhc.exe')
+
+    configure_file("${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in" conf.py @ONLY)
+    add_custom_target(doc ALL DEPENDS doc-html doc-man COMMENT "Building documentation...")
+    if(PDFLATEX_FOUND)
+        # if this still fails on Debian/Ubuntu, run
+        # apt-get install texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
+        add_custom_target(doc-latex  ${SPHINX_EXECUTABLE}
+		                     -q -c . -b latex
+				     -d ${SPHINX_CACHE_DIR}
+				     ${CMAKE_CURRENT_SOURCE_DIR}
+				     ${SPHINX_PDF_DIR} )
+        add_custom_target(doc-pdf make -C ${SPHINX_PDF_DIR} all-pdf
+		                  DEPENDS doc-latex )
+        add_dependencies(doc doc-pdf)
+    endif(PDFLATEX_FOUND)
+    if (EXISTS ${QT_QCOLLECTIONGENERATOR_EXECUTABLE})
+        add_custom_target( doc-qch-sphinx ${SPHINX_EXECUTABLE}
+		                          -q -c . -b qthelp
+				          -d ${SPHINX_CACHE_DIR}
+					  ${CMAKE_CURRENT_SOURCE_DIR}
+					  ${SPHINX_QCH_DIR} )
+        add_custom_target( doc-qch ${QT_QCOLLECTIONGENERATOR_EXECUTABLE}
+		                   ${SPHINX_QCH_DIR}/*.qhcp
+				   DEPENDS doc-qch-sphinx )
+        add_dependencies(doc doc-qch)
+    endif()
+    add_custom_target( doc-html ${SPHINX_EXECUTABLE}
+	                        -q -c . -b html
+				-d ${SPHINX_CACHE_DIR}
+				${CMAKE_CURRENT_SOURCE_DIR}
+				${SPHINX_HTML_DIR} )
+    add_custom_target( doc-man  ${SPHINX_EXECUTABLE}
+	                        -q -c . -b man
+				-d ${SPHINX_CACHE_DIR}
+				${CMAKE_CURRENT_SOURCE_DIR}
+				${SPHINX_MAN_DIR} )
+    ## Building CHM files requires HTML Help Workshop. Since it requires wine
+    ## with special dependencies, it's impossible to write a cmake check for it.
+    ## This is why doc-chm is not a dependency for doc. Instead, run
+    ## doc/scripts/htmlhelp.exe to install them and run this target
+    ## explicitly.
+    add_custom_target( doc-chm-sphinx  ${SPHINX_EXECUTABLE}
+	                               -q -c . -b htmlhelp
+	                               -D html_theme=basic
+                                       -d ${SPHINX_CACHE_DIR}
+                                       ${CMAKE_CURRENT_SOURCE_DIR}
+                                       ${SPHINX_HTMLHELP_DIR} )
+    add_custom_target( doc-chm pushd ${SPHINX_HTMLHELP_DIR}; ${MSHTML_COMPILER} *.hhp; popd
+				   DEPENDS doc-chm-sphinx )
+endif(SPHINX_FOUND)

doc/conf.py → doc/conf.py.in

@@ -40,17 +40,17 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'ownCloud Clientistrators Manual'
+project = u'ownCloud Client Manual'
 copyright = u'2012, The ownCloud developers'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '4.5'
+version = '@VERSION_MAJOR@.@VERSION_MINOR@'
 # The full version, including alpha/beta/rc tags.
-release = '4.5'
+release = '@VERSION@'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -71,7 +71,7 @@
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
-
+2
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
@@ -101,9 +101,6 @@
 # a list of builtin themes.
 #html_theme = 'bootstrap'
 html_theme = 'default'
-html_theme_options = {
-    "relbarbgcolor": "black"   
-}
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
@@ -216,7 +213,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'owncloudadminmanual', u'ownCloud Client Manual',
+    ('index', 'owncloud', u'ownCloud Client Manual',
      [u'The ownCloud developers'], 1)
 ]
 

doc/scripts/README.rst

@@ -0,0 +1,12 @@
+Doc Build Convenience Scripts
+=============================
+
+* ``htmlhelp.sh``: A script to install Microsoft HTML Workshop on Linux or Mac OS using Wine, along with some dependencies.
+* ``htmlhelp.reg``: Registry file to override some DLLs with their native version and set the right Windows version.
+
+Those files have been taken from the HTML Help Project (http://code.google.com/p/htmlhelp/wiki/HHW4Wine).
+
+License
+-------
+
+The HTML Help Project has licensed its software under LGPLv3 terms.

doc/scripts/htmlhelp.reg

@@ -0,0 +1,12 @@
+REGEDIT4
+
+[HKEY_CURRENT_USER\Software\Wine]
+"Version"="win2k"
+
+[HKEY_CURRENT_USER\Software\Wine\AppDefaults\hhc.exe\DllOverrides]
+"itircl"="native"
+"itss"="native"
+
+[HKEY_CURRENT_USER\Software\Wine\AppDefaults\hhw.exe\DllOverrides]
+"itircl"="native"
+"itss"="native"

doc/scripts/htmlhelp.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+
+WINEPREFIX=${WINEPREFIX:=$HOME/.wine}
+
+test -d "$WINEPREFIX" || wineprefixcreate
+
+# Setup the registry
+wine regedit htmlhelp.reg
+
+# Install HTML Help Workshop
+wget 'http://go.microsoft.com/fwlink/?LinkId=14188' -O htmlhelp.exe
+wine htmlhelp.exe
+
+# Install ITSS.DLL
+cabextract -F hhupd.exe htmlhelp.exe
+cabextract -F itircl.dll hhupd.exe
+cabextract -F itss.dll hhupd.exe
+cp -a itircl.dll "$WINEPREFIX/drive_c/windows/system32/"
+cp -a itss.dll "$WINEPREFIX/drive_c/windows/system32/"
+wine regsvr32 /s 'C:\WINDOWS\SYSTEM32\itircl.dll'
+wine regsvr32 /s 'C:\WINDOWS\SYSTEM32\itss.dll'
+
+# Install MFC40.DLL
+wget -N http://activex.microsoft.com/controls/vc/mfc40.cab
+cabextract -F mfc40.exe mfc40.cab
+cabextract -F mfc40.dll mfc40.exe
+cp -a mfc40.dll "$WINEPREFIX/drive_c/windows/system32/"