kicad-developers team mailing list archive

[John Beard <john.j.beard@xxxxxxxxx>]

Hi,

This is a patch to generate docsets using our existing doxygen set-up.
Docset documentation makes it very easy to quickly browse the docs
using Zeal and similar [1], which means you can get IDE integration
and other nice things.

The patch adds a "make docset" target. To actually build the docset,
you will need doxytag2zealdb, a Python program available with pip.

There is a strange extraneous endif() in the existing version Cmake as
well, which I
cannot explain why it currently works at all in its current form!

The docset can be used to construct a docset feed using the CI
infrastructure. Basically you need to host the TGZ somewhere and then
provide an XML which changes the version and the link as needed. Zeal
then picks up new version availability when checked.

I have a hastily constructed feed available here [2]. This means you
can start using a nightly-ish docset today, but updates are not done
by a CI system. It should be as simple as adding this URL in Zeal [3].

Cheers,

John

[1]: zealdocs.org
[2]: https://github.com/johnbeard/kicad-docset
[3]: https://raw.githubusercontent.com/johnbeard/kicad-docset/master/feeds/master/KiCad.xml

From 12e3406c080d96a3dd1195c7c402832eab390145 Mon Sep 17 00:00:00 2001
From: John Beard <john.j.beard@xxxxxxxxx>
Date: Mon, 26 Nov 2018 21:14:21 +0000
Subject: [PATCH] Docs: add docset generation target

This is a CMake (non-ALL) target that will build a Zeal-compatible
docset from a version of the doxygen HTML.

To do this, doxytag2zeal is used.
---
 CMakeLists.txt                            |   2 +
 CMakeModules/CreateGitVersionHeader.cmake |   1 -
 Documentation/docset/CMakeLists.txt       | 131 ++++++++++++++++++++++
 Documentation/docset/icon-16.png          | Bin 0 -> 271 bytes
 4 files changed, 133 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/docset/CMakeLists.txt
 create mode 100644 Documentation/docset/icon-16.png

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 982209910..0aeca0239 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -836,6 +836,8 @@ if( DOXYGEN_FOUND )
         DEPENDS Doxyfile
         COMMENT "building developer's resource docs into directory Documentation/development/doxygen/html"
         )
+
+    add_subdirectory(Documentation/docset)
 else()
     message( STATUS "WARNING: Doxygen not found - doxygen-docs (Source Docs) target not created" )
 endif()
diff --git a/CMakeModules/CreateGitVersionHeader.cmake b/CMakeModules/CreateGitVersionHeader.cmake
index 43ab16031..f465534f0 100644
--- a/CMakeModules/CreateGitVersionHeader.cmake
+++ b/CMakeModules/CreateGitVersionHeader.cmake
@@ -39,7 +39,6 @@ macro( create_git_version_header _git_src_path )
             ERROR_VARIABLE _git_log_error
             RESULT_VARIABLE _git_log_result
             OUTPUT_STRIP_TRAILING_WHITESPACE)
-        endif()
 
         set( ENV{LC_ALL} ${_Git_SAVED_LC_ALL} )
     endif( GIT_FOUND )
diff --git a/Documentation/docset/CMakeLists.txt b/Documentation/docset/CMakeLists.txt
new file mode 100644
index 000000000..006a1700b
--- /dev/null
+++ b/Documentation/docset/CMakeLists.txt
@@ -0,0 +1,131 @@
+#
+#  This program source code file is part of KICAD, a free EDA CAD application.
+#
+#  Copyright (C) 2018 KiCad Developers, see AUTHORS.txt for contributors.
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program; if not, you may find one here:
+#  http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+#  or you may search the http://www.gnu.org website for the version 2 license,
+#  or you may write to the Free Software Foundation, Inc.,
+#  51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
+
+# Build file for docset generation.
+#
+# Docsets are generated from the Doxygen docs by this process:
+# * Modify the existing doxygen file for a docset-friendly output
+# * Run doxygen to generate normal docygen output
+# * Run a makefile made by doxygen to start the docset
+# * Run doxytag2zealdb to generate the docset index
+# * Make a couple of changes to the Plist file and add icons
+
+find_program(DOXYTAG2ZEALDB doxytag2zealdb)
+find_program(SED sed)
+
+if(DOXYGEN_FOUND AND DOXYTAG2ZEALDB AND SED)
+
+    function(get_kicad_doc_version RESULT_NAME)
+
+        include( ${CMAKE_MODULE_PATH}/CreateGitVersionHeader.cmake )
+        create_git_version_header(${CMAKE_SOURCE_DIR})
+
+        # Now we have KICAD_VERSION, but it's got () around it
+        string(REPLACE "(" "" KICAD_VERSION ${KICAD_VERSION})
+        string(REPLACE ")" "" KICAD_VERSION ${KICAD_VERSION})
+
+        set (${RESULT_NAME} ${KICAD_VERSION} PARENT_SCOPE)
+
+    endfunction()
+
+    # The DocSet's bundle ID, which is used for most of the ID's
+    set(BUNDLE_ID KiCad)
+
+    # The source for the doxygen config
+    set(SRC_DOXYFILE ${CMAKE_SOURCE_DIR}/Doxyfile)
+
+    # A new doxyfile with the original, plus some extra config
+    set(DOCSET_DOXYFILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+    # Various pieces of the docset
+    set(DOCSET_LOC ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html/${BUNDLE_ID}.docset)
+    set(DOXY_MAKEFILE ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html/Makefile)
+    set(DOXY_TAG_FILE ${CMAKE_CURRENT_BINARY_DIR}/${BUNDLE_ID}.tag)
+    set(DOCSET_PLIST ${DOCSET_LOC}/Contents/Info.plist)
+    set(DOCSET_DSIDX ${DOCSET_LOC}/Contents/Resources/docSet.dsidx)
+
+    #icon files
+    set(DOCSET_SRC_ICON16 ${CMAKE_CURRENT_SOURCE_DIR}/icon-16.png)
+    set(DOCSET_ICON16 ${DOCSET_LOC}/icon.png)
+
+    get_kicad_doc_version(KICAD_DOC_VERSION)
+
+    # copy and modify the "normal" Doxyfile
+    file(COPY ${SRC_DOXYFILE} DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
+    file(APPEND ${DOCSET_DOXYFILE} "
+
+# Added for DocSet generation
+OUTPUT_DIRECTORY        = ${CMAKE_CURRENT_BINARY_DIR}/doxygen
+PROJECT_NAME            = ${BUNDLE_ID}
+PROJECT_NUMBER          = ${KICAD_DOC_VERSION}
+GENERATE_DOCSET         = YES
+DOCSET_FEEDNAME         = ${BUNDLE_ID}
+DOCSET_BUNDLE_ID        = ${BUNDLE_ID}
+DISABLE_INDEX           = YES
+GENERATE_TREEVIEW       = NO
+SEARCHENGINE            = NO
+GENERATE_TAGFILE        = ${DOXY_TAG_FILE}"
+    )
+
+    add_custom_command(
+        COMMAND ${DOXYGEN_EXECUTABLE} ${DOCSET_DOXYFILE}
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+        OUTPUT ${DOXY_TAG_FILE} ${DOXY_MAKEFILE}
+        DEPENDS ${DOCSET_DOXYFILE}
+        COMMENT "Generating Doxygen for DocSet"
+    )
+
+    # Generate the skeleton of the docset
+    # And modify the plist: DocSetPlatformFamily is used for the prefix in Zeal,
+    add_custom_command(
+        COMMAND make || true
+        COMMAND ${SED} -i "/<key>DocSetPlatformFamily<\\/key>/!b;n;s/doxygen/${BUNDLE_ID}/" ${DOCSET_PLIST}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
+        DEPENDS ${DOXY_MAKEFILE}
+        OUTPUT ${DOCSET_PLIST}
+        COMMENT "Running doxygen-generated makefile"
+        VERBATIM
+    )
+
+    add_custom_command(
+        COMMAND ${DOXYTAG2ZEALDB} --tag ${DOXY_TAG_FILE}
+            --db ${DOCSET_DSIDX}
+            --include-parent-scopes
+            --include-function-signatures
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
+        DEPENDS ${DOCSET_PLIST} ${DOXY_TAG_FILE}
+        OUTPUT ${DOCSET_DSIDX}
+        COMMENT "Generating docset index"
+    )
+
+    add_custom_command(
+        COMMAND ${CMAKE_COMMAND} -E copy ${DOCSET_SRC_ICON16} ${DOCSET_ICON16}
+        DEPENDS ${DOCSET_DSIDX} ${DOCSET_SRC_ICON16}
+        OUTPUT ${DOCSET_ICON16}
+        COMMENT "Copying docset icons"
+    )
+
+    add_custom_target(docset
+        DEPENDS ${DOCSET_ICON16}
+    )
+
+endif()
\ No newline at end of file
diff --git a/Documentation/docset/icon-16.png b/Documentation/docset/icon-16.png
new file mode 100644
index 0000000000000000000000000000000000000000..9f8f6e3549830be5093f4bfeb98f006c073e8bc1
GIT binary patch
literal 271
zcmeAS@N?(olHy`uVBq!ia0vp^0wB!73?$#)eFPF<Nq6*hWMJ6X&;2Kn7072S4sv&5
zSa(k5C6J>V;1lBNlUXRPneiVEDi|P4UGI%R#?p;<|5q?vxb`ls`sm-k|BR*n?gVP&
zC<*clX1JuwpSUk2tXAsAE1(!>fk$L91A~Y#2s5^oO(_BjhI_g=hHzX@PGD#*U}F;#
zS17nU_rQXSj7+;{OPZvedojmyG4m0Ni<X<2&qOeaFc^oOd-Gy8XHo-;LXWfon-9wh
vwnGdrn+*J%BpoIn<k=AGz|6~f&;jV5mzL}FrtUiow1UCY)z4*}Q$iB}`F~^x

literal 0
HcmV?d00001

-- 
2.19.2