Mercurial > irccd

changeset 275:c143682678b9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
CMake: improve documentation related to plugins
author David Demelier <markand@malikania.fr>
date Thu, 29 Sep 2016 12:41:19 +0200
parents 750157368a42
children 5795a1769de5
files CMakeLists.txt cmake/function/IrccdBuildHtml.cmake cmake/function/IrccdDefinePlugin.cmake doc/html/CMakeLists.txt doc/html/dev/socket-commands.md doc/html/index.md doc/html/resources/metadata.yml doc/html/resources/template.html plugins/ask/ask.md plugins/auth/auth.md plugins/hangman/hangman.md plugins/history/history.md plugins/logger/logger.md plugins/plugin/plugin.md plugins/roulette/roulette.md
diffstat 15 files changed, 207 insertions(+), 92 deletions(-) [+]
line wrap: on
line diff
--- a/CMakeLists.txt	Wed Sep 28 13:39:15 2016 +0200
+++ b/CMakeLists.txt	Thu Sep 29 12:41:19 2016 +0200
@@ -60,6 +60,7 @@
 
 include(CMakeParseArguments)
 
+include(cmake/function/IrccdBuildHtml.cmake)
 include(cmake/function/IrccdDefineExecutable.cmake)
 include(cmake/function/IrccdDefineLibrary.cmake)
 include(cmake/function/IrccdDefineMan.cmake)
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/cmake/function/IrccdBuildHtml.cmake	Thu Sep 29 12:41:19 2016 +0200
@@ -0,0 +1,159 @@
+#
+# IrccdBuildHtml.cmake -- CMake build system for irccd
+#
+# Copyright (c) 2013-2016 David Demelier <markand@malikania.fr>
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+#
+
+include(CMakeParseArguments)
+
+#
+# irccd_build_html
+# -------------------------------------------------------------------
+#
+# irccd_build_html(
+#   COMPONENT (Optional) install the output documentation as the given component
+#   OUTPUT (Optional) override output path
+#   OUTPUT_VAR (Optional) store the output file in the output variable
+#   SOURCE the source markdown file
+# )
+#
+# Create a rule to build the markdown file specified by SOURCE parameter.
+#
+# By default, the output file is built in the same directory relative to the
+# current project. Specifying /foo/bar/baz/foo.md as SOURCE from the
+# directory /foo/var ends in an output file baz/foo.html.
+#
+# The output file path can be overriden with the OUTPUT variable which must be
+# relative and must contain the filename without extension (e.g. api/misc/Foo).
+#
+# This macro does not create a target, just the output rule and the output file
+# can be retrieved using the OUTPUT_VAR variable.
+#
+# Example:
+#
+# irccd_build_html(
+#   COMPONENT documentation
+#   OUTPUT dev/howto-create-a-plugin
+#   SOURCE myfile.md
+#   OUTPUT_VAR output
+# )
+#
+# add_custom_target(mytarget DEPENDS ${output})
+#
+# It's perfectly safe to call this macro multiple times with the same COMPONENT.
+#
+
+macro(irccd_build_html)
+    set(oneValueArgs COMPONENT OUTPUT OUTPUT_VAR SOURCE)
+
+    cmake_parse_arguments(HTML "" "${oneValueArgs}" "" ${ARGN})
+
+    if (NOT HTML_SOURCE)
+        message(FATAL_ERROR "Missing SOURCE parameter")
+    endif ()
+
+    #
+    # Example with SOURCES set to CMAKE_CURRENT_SOURCE_DIR/api/event/onMessage.md
+    #
+    # Extract the following variables:
+    #
+    # dirname:      api/event
+    # basename:     onMessage
+    # baseurl:      ../../
+    #
+    if (HTML_OUTPUT)
+        if (IS_ABSOLUTE ${HTML_OUTPUT})
+            message(FATAL_ERROR "OUTPUT variable must not be absolute")
+        endif ()
+
+        get_filename_component(dirname ${HTML_OUTPUT} DIRECTORY)
+        get_filename_component(basename ${HTML_OUTPUT} NAME)
+    else()
+        get_filename_component(dirname ${HTML_SOURCE} DIRECTORY)
+        file(RELATIVE_PATH dirname ${CMAKE_CURRENT_SOURCE_DIR} ${dirname})
+        get_filename_component(basename ${HTML_SOURCE} NAME)
+    endif ()
+
+    # Remove extension from basename.
+    string(REGEX REPLACE "^(.*)\\.md$" "\\1" basename ${basename})
+
+    file(
+            RELATIVE_PATH
+            baseurl
+            ${IRCCD_FAKEROOTDIR}/${WITH_DOCDIR}/${dirname}
+            ${IRCCD_FAKEROOTDIR}/${WITH_DOCDIR}
+    )
+
+    if (baseurl STREQUAL "")
+        set(baseurl "./")
+    endif ()
+
+#    message("==> dumping ${HTML_SOURCE} <==")
+#    message("  -> basename: ${basename}")
+#    message("  -> dirname: ${dirname}")
+#    message("  -> baseurl: ${baseurl}")
+
+    # Replace CMake variables.
+    configure_file(
+        ${HTML_SOURCE}
+        ${CMAKE_CURRENT_BINARY_DIR}/${dirname}/${basename}.md
+        @ONLY
+    )
+
+    # Create a list of parents for the breadcrumb widget.
+    string(REPLACE "/" ";" parentlist "${dirname}")
+    set(parents "  -\n")
+    set(parents "${parents}    name: \"index\"\n")
+    set(parents "${parents}    path: \"${baseurl}index.html\"\n")
+
+    set(path "${baseurl}")
+    foreach (p ${parentlist})
+        set(path "${path}${p}/")
+        set(parents "${parents}  -\n")
+        set(parents "${parents}    name: \"${p}\"\n")
+        set(parents "${parents}    path: \"${path}index.html\"\n")
+    endforeach ()
+
+    configure_file(
+        ${html_SOURCE_DIR}/resources/metadata.yml
+        ${CMAKE_CURRENT_BINARY_DIR}/${dirname}/${basename}.yml
+    )
+
+    # Pandoc the file.
+    pandoc(
+        OUTPUT ${IRCCD_FAKEROOTDIR}/${WITH_DOCDIR}/${dirname}/${basename}.html
+        SOURCES
+            ${CMAKE_CURRENT_BINARY_DIR}/${dirname}/${basename}.yml
+            ${CMAKE_CURRENT_BINARY_DIR}/${dirname}/${basename}.md
+        DEPENDS ${HTML_SOURCE}
+        TEMPLATE ${html_SOURCE_DIR}/resources/template.html
+        FROM markdown
+        TO html5
+        STANDALONE TOC MAKE_DIRECTORY
+    )
+
+    # Install the documentation file as component if provided.
+    if (HTML_COMPONENT)
+        install(
+            FILES ${IRCCD_FAKEROOTDIR}/${WITH_DOCDIR}/${dirname}/${basename}.html
+            COMPONENT ${HTML_COMPONENT}
+            DESTINATION ${WITH_DOCDIR}/${dirname}
+        )
+    endif ()
+
+    if (HTML_OUTPUT_VAR)
+        set(${HTML_OUTPUT_VAR} ${IRCCD_FAKEROOTDIR}/${WITH_DOCDIR}/${dirname}/${basename}.html)
+    endif ()
+endmacro ()
--- a/cmake/function/IrccdDefinePlugin.cmake	Wed Sep 28 13:39:15 2016 +0200
+++ b/cmake/function/IrccdDefinePlugin.cmake	Thu Sep 29 12:41:19 2016 +0200
@@ -110,8 +110,8 @@
 
 function(irccd_define_plugin)
     set(options "")
-    set(oneValueArgs NAME TYPE SCRIPT)
-    set(multiValueArgs DOCS SOURCES)
+    set(oneValueArgs NAME DOCS TYPE SCRIPT)
+    set(multiValueArgs SOURCES)
 
     cmake_parse_arguments(PLG "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
@@ -129,24 +129,11 @@
 
         # Optional documentation.
         if (PLG_DOCS AND WITH_HTML)
-            set(basedocdir ${IRCCD_FAKEROOTDIR}/${WITH_DOCDIR})
-            set(PLG_OUTPUT_DOC ${basedocdir}/plugin/${PLG_NAME}.html)
-            file(RELATIVE_PATH baseurl ${basedocdir}/plugin ${basedocdir})
-
-            pandoc(
-                OUTPUT ${basedocdir}/plugin/${PLG_NAME}.html
-                SOURCES ${PLG_DOCS}
-                TEMPLATE ${html_SOURCE_DIR}/resources/template.html
-                DEPENDS ${html_SOURCE_DIR}/resources/template.html
-                ARGS -Vguide
-                VARIABLE baseurl:${baseurl}
-                FROM markdown TO html5
-                STANTALONE MAKE_DIRECTORY TOC
-            )
-            install(
-                FILES ${basedocdir}/plugin/${PLG_NAME}.html
+            irccd_build_html(
+                SOURCE ${PLG_DOCS}
+                OUTPUT plugin/${PLG_NAME}
                 COMPONENT ${PLG_NAME}
-                DESTINATION ${WITH_DOCDIR}/plugin
+                OUTPUT_VAR PLG_OUTPUT_DOC
             )
         endif ()
 
--- a/doc/html/CMakeLists.txt	Wed Sep 28 13:39:15 2016 +0200
+++ b/doc/html/CMakeLists.txt	Thu Sep 29 12:41:19 2016 +0200
@@ -163,81 +163,14 @@
     ${html_SOURCE_DIR}/resources/js/jquery.min.js
 )
 
-#
-# For each files, define the following variables:
-#
-# - baseurl: relative path to get climb to the root documentation (e.g. ../../)
-# - inputbase: file name with it's base directory (e.g. api/event/onMessage.md)
-# - inputname: file name without it's directory (e.g. onMessage.md)
-# - outputbase: file name, directory and html extension
-#   (e.g api/event/onMessage.html)
-#
 if (WITH_HTML)
     foreach (file ${HTML_SOURCES})
-        # 'baseurl': compute the tree from the file to this directory.
-        # 'inputbase': the canonical file name.
-        get_filename_component(fulldirectory ${file} DIRECTORY)
-        get_filename_component(inputname ${file} NAME_WE)
-        file(RELATIVE_PATH baseurl ${fulldirectory} ${html_SOURCE_DIR})
-
-        # 'inputbase': relative to this source directory.
-        file(RELATIVE_PATH inputbase ${html_SOURCE_DIR} ${file})
-
-        # 'outputbase': replace .md to .html as file extension.
-        string(REGEX REPLACE "^(.*)\\.md$" "\\1.html" outputbase ${inputbase})
-
-        # If file is located at root, replace empty baseurl with "./".
-        if (baseurl STREQUAL "")
-            set(baseurl "./")
-        endif ()
-
-        # Configure the file so it can resolve CMake variables.
-        configure_file(
-            ${file}
-            ${html_BINARY_DIR}/${inputbase}
+        irccd_build_html(
+            SOURCE ${file}
+            OUTPUT_VAR output
         )
-
-        # Create a list of parents for the breadcrumb widget.
-        get_filename_component(parentlist ${inputbase} DIRECTORY)
-        string(REPLACE "/" ";" parentlist "${parentlist}")
-        set(parents "  -\n")
-        set(parents "${parents}    name: \"index\"\n")
-        set(parents "${parents}    path: \"${baseurl}index.html\"\n")
+        list(APPEND OUTPUTS ${output})
 
-        set(path "${baseurl}")
-        foreach (p ${parentlist})
-            set(path "${path}${p}/")
-            set(parents "${parents}  -\n")
-            set(parents "${parents}    name: \"${p}\"\n")
-            set(parents "${parents}    path: \"${path}index.html\"\n")
-        endforeach ()
-
-        configure_file(
-            ${html_SOURCE_DIR}/resources/metadata.yml
-            ${html_BINARY_DIR}/${inputbase}.yml
-        )
-
-        # Create an output target to that file.
-        pandoc(
-            OUTPUT ${IRCCD_FAKEROOTDIR}/${WITH_DOCDIR}/${outputbase}
-            SOURCES
-                ${html_BINARY_DIR}/${inputbase}.yml
-                ${html_BINARY_DIR}/${inputbase}
-            DEPENDS ${file}
-            TEMPLATE ${html_SOURCE_DIR}/resources/template.html
-            VARIABLE baseurl:${baseurl}
-            FROM markdown
-            TO html5
-            STANDALONE TOC MAKE_DIRECTORY
-        )
-
-        list(APPEND OUTPUTS ${IRCCD_FAKEROOTDIR}/${WITH_DOCDIR}/${outputbase})
-        install(
-            FILES ${IRCCD_FAKEROOTDIR}/${WITH_DOCDIR}/${outputbase}
-            COMPONENT docs
-            DESTINATION ${WITH_DOCDIR}
-            RENAME ${outputbase}
-        )
     endforeach ()
 
     add_custom_target(
--- a/doc/html/dev/socket-commands.md	Wed Sep 28 13:39:15 2016 +0200
+++ b/doc/html/dev/socket-commands.md	Thu Sep 29 12:41:19 2016 +0200
@@ -1,3 +1,8 @@
+---
+title: Irccd socket API
+guide: true
+---
+
 ## Commands
 
 The following commands are available. Please note that a lot of commands require a server as the first argument, it’s
--- a/doc/html/index.md	Wed Sep 28 13:39:15 2016 +0200
+++ b/doc/html/index.md	Thu Sep 29 12:41:19 2016 +0200
@@ -4,3 +4,25 @@
 ---
 
 Welcome to the irccd documentation.
+
+# Building
+
+  - [Build from sources](build/build-from-sources.html)
+  - [Build options](build/build-options.html)
+
+# Running
+
+  - [Configure irccd](irccd/configuring.html)
+  - [Configure irccdctl](irccdctl/configuring.html)
+
+# Plugins
+
+  - [Javascript plugin introduction](dev/plugin-javascript-introduction.html)
+  - [Javascript API](api/index.html)
+
+# Miscellaneous
+
+  - [Common patterns and formatting](misc/common-patterns-and-formatting.html)
+  - [Configuration file syntax](misc/configuration-syntax.html)
+  - [Network protocol](dev/socket-protocol.html)
+  - [Network commands](dev/socket-commands.html)
--- a/doc/html/resources/metadata.yml	Wed Sep 28 13:39:15 2016 +0200
+++ b/doc/html/resources/metadata.yml	Thu Sep 29 12:41:19 2016 +0200
@@ -1,5 +1,6 @@
 ---
+baseurl: "@baseurl@"
 parents:
 @parents@
-filename: "@inputname@"
+basename: "@basename@"
 ---
--- a/doc/html/resources/template.html	Wed Sep 28 13:39:15 2016 +0200
+++ b/doc/html/resources/template.html	Thu Sep 29 12:41:19 2016 +0200
@@ -89,7 +89,7 @@
 $for(parents)$
         <li><a href="$parents.path$">$parents.name$</a></li>
 $endfor$
-        <li class="active">$filename$</li>
+        <li class="active">$basename$</li>
       </ol><!-- !breadcrumb -->
 
     <!-- Page body for JavaScript -->
--- a/plugins/ask/ask.md	Wed Sep 28 13:39:15 2016 +0200
+++ b/plugins/ask/ask.md	Thu Sep 29 12:41:19 2016 +0200
@@ -1,6 +1,7 @@
 ---
 title: "Ask plugin"
 header: "Ask plugin"
+guide: yes
 ---
 
 The plugin **ask** is funny script that helps you in your life. It will tells you if you will be rich, famous and so on.
--- a/plugins/auth/auth.md	Wed Sep 28 13:39:15 2016 +0200
+++ b/plugins/auth/auth.md	Thu Sep 29 12:41:19 2016 +0200
@@ -1,6 +1,7 @@
 ---
 title: "Auth plugin"
 header: "Auth plugin"
+guide: yes
 ---
 
 The plugin **auth** provides generic authentication to the most popular services.
--- a/plugins/hangman/hangman.md	Wed Sep 28 13:39:15 2016 +0200
+++ b/plugins/hangman/hangman.md	Thu Sep 29 12:41:19 2016 +0200
@@ -1,6 +1,7 @@
 ---
 title: "Hangman plugin"
 header: "Hangman plugin"
+guide: yes
 ---
 
 Hangman is a plugin to play the hangman game.
--- a/plugins/history/history.md	Wed Sep 28 13:39:15 2016 +0200
+++ b/plugins/history/history.md	Thu Sep 29 12:41:19 2016 +0200
@@ -1,6 +1,7 @@
 ---
 title: "History plugin"
 header: "History plugin"
+guide: yes
 ---
 
 The plugin **history** is used to check when someone has been seen for the last time on a channel. For that purpose,
--- a/plugins/logger/logger.md	Wed Sep 28 13:39:15 2016 +0200
+++ b/plugins/logger/logger.md	Thu Sep 29 12:41:19 2016 +0200
@@ -1,6 +1,7 @@
 ---
 title: "Logger plugin"
 header: "Logger plugin"
+guide: yes
 ---
 
 The plugin **logger** may be used to log everything you want. It supports the following events:
--- a/plugins/plugin/plugin.md	Wed Sep 28 13:39:15 2016 +0200
+++ b/plugins/plugin/plugin.md	Thu Sep 29 12:41:19 2016 +0200
@@ -1,6 +1,7 @@
 ---
 title: "Plugin plugin"
 header: "Plugin plugin"
+guide: yes
 ---
 
 The plugin **plugin** let you inspect loaded plugins.
--- a/plugins/roulette/roulette.md	Wed Sep 28 13:39:15 2016 +0200
+++ b/plugins/roulette/roulette.md	Thu Sep 29 12:41:19 2016 +0200
@@ -1,6 +1,7 @@
 ---
 title: "Roulette plugin"
 header: "Roulette plugin"
+guide: yes
 ---
 
 The plugin **roulette** is a funny script that let you do a russian roulette game but without any injuries.