Skip to content

Commit 78c7dc9

Browse files
author
Daniel Molkentin
committed
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.
1 parent f7b7669 commit 78c7dc9

9 files changed

+472
-9
lines changed

‎CMakeLists.txt

+4-1
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@ endif()
4040
find_package(Qt4 4.6.0 COMPONENTS QtCore QtGui QtXml QtNetwork QtTest REQUIRED )
4141
find_package(Csync)
4242
find_package(INotify)
43+
find_package(Sphinx)
44+
find_package(PdfLatex)
4345

4446
set(WITH_CSYNC CSYNC_FOUND)
4547
set(USE_INOTIFY ${INOTIFY_FOUND})
@@ -81,6 +83,8 @@ file( GLOB TRANS_FILES ${CMAKE_SOURCE_DIR}/translations/mirall_*.ts)
8183
set(TRANSLATIONS ${TRANS_FILES})
8284

8385
add_subdirectory(src)
86+
add_subdirectory(doc)
87+
8488
if(UNIT_TESTING)
8589
include(CTest)
8690
enable_testing()
@@ -92,4 +96,3 @@ if(BUILD_OWNCLOUD_OSX_BUNDLE)
9296
else()
9397
install( FILES sync-exclude.lst DESTINATION ${CMAKE_INSTALL_SYSCONFDIR} )
9498
endif()
95-

‎COPYING.documentation

+319
Large diffs are not rendered by default.

‎cmake/modules/FindPdfLatex.cmake

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
find_program(PDFLATEX_EXECUTABLE NAMES pdflatex
2+
HINTS
3+
$ENV{PDFLATEX_DIR}
4+
PATH_SUFFIXES bin
5+
DOC "PDF LaTeX"
6+
)
7+
8+
include(FindPackageHandleStandardArgs)
9+
10+
find_package_handle_standard_args(PdfLatex DEFAULT_MSG
11+
PDFLATEX_EXECUTABLE
12+
)
13+
14+
mark_as_advanced(
15+
PDFLATEX_EXECUTABLE
16+
)

‎cmake/modules/FindSphinx.cmake

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
find_program(SPHINX_EXECUTABLE NAMES sphinx-build
2+
HINTS
3+
$ENV{SPHINX_DIR}
4+
PATH_SUFFIXES bin
5+
DOC "Sphinx documentation generator"
6+
)
7+
8+
include(FindPackageHandleStandardArgs)
9+
10+
find_package_handle_standard_args(Sphinx DEFAULT_MSG
11+
SPHINX_EXECUTABLE
12+
)
13+
14+
mark_as_advanced(
15+
SPHINX_EXECUTABLE
16+
)

‎doc/CMakeLists.txt

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
if(SPHINX_FOUND)
2+
3+
# Sphinx cache with pickled ReST documents
4+
set(SPHINX_CACHE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees")
5+
# HTML output directory
6+
set(SPHINX_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/html")
7+
set(SPHINX_MAN_DIR "${CMAKE_CURRENT_BINARY_DIR}/man")
8+
set(SPHINX_PDF_DIR "${CMAKE_CURRENT_BINARY_DIR}/latex")
9+
set(SPHINX_QCH_DIR "${CMAKE_CURRENT_BINARY_DIR}/qthelp")
10+
set(SPHINX_HTMLHELP_DIR "${CMAKE_CURRENT_BINARY_DIR}/htmlhelp")
11+
set(MSHTML_COMPILER wine 'C:\\Program Files\\HTML Help Workshop\\hhc.exe')
12+
13+
configure_file("${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in" conf.py @ONLY)
14+
add_custom_target(doc ALL DEPENDS doc-html doc-man COMMENT "Building documentation...")
15+
if(PDFLATEX_FOUND)
16+
# if this still fails on Debian/Ubuntu, run
17+
# apt-get install texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
18+
add_custom_target(doc-latex ${SPHINX_EXECUTABLE}
19+
-q -c . -b latex
20+
-d ${SPHINX_CACHE_DIR}
21+
${CMAKE_CURRENT_SOURCE_DIR}
22+
${SPHINX_PDF_DIR} )
23+
add_custom_target(doc-pdf make -C ${SPHINX_PDF_DIR} all-pdf
24+
DEPENDS doc-latex )
25+
add_dependencies(doc doc-pdf)
26+
endif(PDFLATEX_FOUND)
27+
if (EXISTS ${QT_QCOLLECTIONGENERATOR_EXECUTABLE})
28+
add_custom_target( doc-qch-sphinx ${SPHINX_EXECUTABLE}
29+
-q -c . -b qthelp
30+
-d ${SPHINX_CACHE_DIR}
31+
${CMAKE_CURRENT_SOURCE_DIR}
32+
${SPHINX_QCH_DIR} )
33+
add_custom_target( doc-qch ${QT_QCOLLECTIONGENERATOR_EXECUTABLE}
34+
${SPHINX_QCH_DIR}/*.qhcp
35+
DEPENDS doc-qch-sphinx )
36+
add_dependencies(doc doc-qch)
37+
endif()
38+
add_custom_target( doc-html ${SPHINX_EXECUTABLE}
39+
-q -c . -b html
40+
-d ${SPHINX_CACHE_DIR}
41+
${CMAKE_CURRENT_SOURCE_DIR}
42+
${SPHINX_HTML_DIR} )
43+
add_custom_target( doc-man ${SPHINX_EXECUTABLE}
44+
-q -c . -b man
45+
-d ${SPHINX_CACHE_DIR}
46+
${CMAKE_CURRENT_SOURCE_DIR}
47+
${SPHINX_MAN_DIR} )
48+
## Building CHM files requires HTML Help Workshop. Since it requires wine
49+
## with special dependencies, it's impossible to write a cmake check for it.
50+
## This is why doc-chm is not a dependency for doc. Instead, run
51+
## doc/scripts/htmlhelp.exe to install them and run this target
52+
## explicitly.
53+
add_custom_target( doc-chm-sphinx ${SPHINX_EXECUTABLE}
54+
-q -c . -b htmlhelp
55+
-D html_theme=basic
56+
-d ${SPHINX_CACHE_DIR}
57+
${CMAKE_CURRENT_SOURCE_DIR}
58+
${SPHINX_HTMLHELP_DIR} )
59+
add_custom_target( doc-chm pushd ${SPHINX_HTMLHELP_DIR}; ${MSHTML_COMPILER} *.hhp; popd
60+
DEPENDS doc-chm-sphinx )
61+
endif(SPHINX_FOUND)

‎doc/conf.py renamed to ‎doc/conf.py.in

+5-8
Original file line numberDiff line numberDiff line change
@@ -40,17 +40,17 @@
4040
master_doc = 'index'
4141

4242
# General information about the project.
43-
project = u'ownCloud Clientistrators Manual'
43+
project = u'ownCloud Client Manual'
4444
copyright = u'2012, The ownCloud developers'
4545

4646
# The version info for the project you're documenting, acts as replacement for
4747
# |version| and |release|, also used in various other places throughout the
4848
# built documents.
4949
#
5050
# The short X.Y version.
51-
version = '4.5'
51+
version = '@VERSION_MAJOR@.@VERSION_MINOR@'
5252
# The full version, including alpha/beta/rc tags.
53-
release = '4.5'
53+
release = '@VERSION@'
5454

5555
# The language for content autogenerated by Sphinx. Refer to documentation
5656
# for a list of supported languages.
@@ -71,7 +71,7 @@
7171

7272
# If true, '()' will be appended to :func: etc. cross-reference text.
7373
#add_function_parentheses = True
74-
74+
2
7575
# If true, the current module name will be prepended to all description
7676
# unit titles (such as .. function::).
7777
#add_module_names = True
@@ -101,9 +101,6 @@
101101
# a list of builtin themes.
102102
#html_theme = 'bootstrap'
103103
html_theme = 'default'
104-
html_theme_options = {
105-
"relbarbgcolor": "black"
106-
}
107104
# The name for this set of Sphinx documents. If None, it defaults to
108105
# "<project> v<release> documentation".
109106
#html_title = None
@@ -216,7 +213,7 @@
216213
# One entry per manual page. List of tuples
217214
# (source start file, name, description, authors, manual section).
218215
man_pages = [
219-
('index', 'owncloudadminmanual', u'ownCloud Client Manual',
216+
('index', 'owncloud', u'ownCloud Client Manual',
220217
[u'The ownCloud developers'], 1)
221218
]
222219

‎doc/scripts/README.rst

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

‎doc/scripts/htmlhelp.reg

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
REGEDIT4
2+
3+
[HKEY_CURRENT_USER\Software\Wine]
4+
"Version"="win2k"
5+
6+
[HKEY_CURRENT_USER\Software\Wine\AppDefaults\hhc.exe\DllOverrides]
7+
"itircl"="native"
8+
"itss"="native"
9+
10+
[HKEY_CURRENT_USER\Software\Wine\AppDefaults\hhw.exe\DllOverrides]
11+
"itircl"="native"
12+
"itss"="native"

‎doc/scripts/htmlhelp.sh

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
#!/bin/sh
2+
3+
WINEPREFIX=${WINEPREFIX:=$HOME/.wine}
4+
5+
test -d "$WINEPREFIX" || wineprefixcreate
6+
7+
# Setup the registry
8+
wine regedit htmlhelp.reg
9+
10+
# Install HTML Help Workshop
11+
wget 'http://go.microsoft.com/fwlink/?LinkId=14188' -O htmlhelp.exe
12+
wine htmlhelp.exe
13+
14+
# Install ITSS.DLL
15+
cabextract -F hhupd.exe htmlhelp.exe
16+
cabextract -F itircl.dll hhupd.exe
17+
cabextract -F itss.dll hhupd.exe
18+
cp -a itircl.dll "$WINEPREFIX/drive_c/windows/system32/"
19+
cp -a itss.dll "$WINEPREFIX/drive_c/windows/system32/"
20+
wine regsvr32 /s 'C:\WINDOWS\SYSTEM32\itircl.dll'
21+
wine regsvr32 /s 'C:\WINDOWS\SYSTEM32\itss.dll'
22+
23+
# Install MFC40.DLL
24+
wget -N http://activex.microsoft.com/controls/vc/mfc40.cab
25+
cabextract -F mfc40.exe mfc40.cab
26+
cabextract -F mfc40.dll mfc40.exe
27+
cp -a mfc40.dll "$WINEPREFIX/drive_c/windows/system32/"

0 commit comments

Comments
 (0)