Mercurial > irccd
changeset 275:c143682678b9
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.