Commit cdf05fa9 authored by Mickaël Turnel's avatar Mickaël Turnel
Browse files

Generate C and C++ doc with doxygen and remove sphinx usage

parent f5bc7cd9
......@@ -188,9 +188,6 @@ if(ENABLE_CXX_WRAPPER OR ENABLE_CSHARP_WRAPPER OR ENABLE_JAVA_WRAPPER OR ENABLE_
check_python_module(pystache)
check_python_module(six)
if(ENABLE_DOC)
check_python_module(sphinx)
check_python_module(javasphinx)
check_python_module(sphinx_csharp)
#check_python_module(swift_domain)
endif()
endif()
......
......@@ -42,7 +42,6 @@ Here the main dependencies listed:
* **python interpreter** and **pystache**, **six** python module (needed for C++/C#/Java wrappers and API documentation)
* **doxygen** and **dot** (needed for C++ wrapper and API documentation)
* **Bzrtp[6]:** zrtp stack used to secure calls
* For API documentation generation: **sphinx**, **javasphinx**, **sphinx_csharp** python modules are needed.
## Build instructions (when used standalone, outside of linphone-sdk)
......
......@@ -21,7 +21,6 @@
############################################################################
add_subdirectory(doxygen)
add_subdirectory(sphinx)
if(ENABLE_JAVADOC)
find_package(Java REQUIRED)
......
......@@ -24,15 +24,25 @@ if(ENABLE_DOC OR ENABLE_CXX_WRAPPER OR ENABLE_CSHARP_WRAPPER OR ENABLE_JAVA_WRAP
find_package(Doxygen REQUIRED)
if(DOXYGEN_FOUND)
set(top_srcdir "${PROJECT_SOURCE_DIR}")
# Check git describe to see if we are on a release or not
set(LINPHONE_STATE "snapshots")
execute_process(COMMAND ${GIT_EXECUTABLE} describe OUTPUT_VARIABLE GIT_DESC)
if(NOT GIT_DESC MATCHES ".*(alpha|beta).*")
set(LINPHONE_STATE "releases")
endif()
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.dox.in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.dox)
set(DOXYGEN_INPUT "")
foreach (HEADER_FILE ${LINPHONE_HEADER_FILES})
string(CONCAT DOXYGEN_INPUT ${DOXYGEN_INPUT} " \"${HEADER_FILE}\"")
endforeach ()
string(CONCAT DOXYGEN_INPUT ${DOXYGEN_INPUT} " \"${CMAKE_CURRENT_SOURCE_DIR}\"")
string(CONCAT DOXYGEN_INPUT ${DOXYGEN_INPUT} " \"${PROJECT_SOURCE_DIR}/coreapi/help/examples/C\"")
string(CONCAT DOXYGEN_INPUT ${DOXYGEN_INPUT} " \"${CMAKE_CURRENT_BINARY_DIR}/doxygen.dox\"")
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
set(DOC_INPUT_FILES ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
${CMAKE_CURRENT_SOURCE_DIR}/doxygen.dox
${CMAKE_CURRENT_BINARY_DIR}/doxygen.dox
${LINPHONE_HEADER_FILES}
)
set(XML_DIR "${CMAKE_CURRENT_BINARY_DIR}/xml")
......@@ -43,6 +53,17 @@ if(ENABLE_DOC OR ENABLE_CXX_WRAPPER OR ENABLE_CSHARP_WRAPPER OR ENABLE_JAVA_WRAP
DEPENDS ${DOC_INPUT_FILES}
)
add_custom_target(linphone-doc ALL DEPENDS "${XML_DIR}/index.xml")
set(C_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/c")
set(LINPHONE_DOXYGEN_C_HTML_DIR ${C_HTML_DIR} PARENT_SCOPE)
add_custom_command(OUTPUT "${C_HTML_DIR}/index.html"
COMMAND ${CMAKE_COMMAND} -E remove -f c/*
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
DEPENDS ${DOC_INPUT_FILES}
)
add_custom_target(linphone-c-html-doc ALL DEPENDS "${C_HTML_DIR}/index.html")
install(DIRECTORY "${C_HTML_DIR}"
DESTINATION "${CMAKE_INSTALL_DATADIR}/doc/liblinphone-${LINPHONE_VERSION}")
endif()
endif()
......@@ -1048,7 +1048,7 @@ IGNORE_PREFIX =
# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
# The default value is: YES.
GENERATE_HTML = NO
GENERATE_HTML = YES
# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
......@@ -1056,7 +1056,7 @@ GENERATE_HTML = NO
# The default directory is: html.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_OUTPUT = html
HTML_OUTPUT = c
# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
# generated HTML page (for example: .htm, .php, .asp).
......
......@@ -5,30 +5,26 @@
*
* @section what_is_it What is liblinphone
*
* Liblinphone is a high level library for bringing SIP video call functionnality
* into an application. It aims at making easy the integration of the SIP
* video calls into any applications. All variants of linphone are directly based
* on it:
* - linphone (gtk interface)
* - linphonec (console interface)
* - linphone for iOS
* - linphone for Android
* Liblinphone is a high-level open source library that integrates all the SIP voice/video and instant messaging features into a single easy-to-use API.
* This is the VoIP SDK engine on which Linphone applications are based.
*
* Liblinphone is GPL (see COPYING file). Please understand the licencing details
* before using it!
* Liblinphone combines our media processing and streaming toolkit (Mediastreamer2) with our user-agent library for SIP signaling (belle-sip).
* Liblinphone has support for a variety of languages, each one has its own reference documentation:
*
* For any use of this library beyond the rights granted to you by the
* GPL license, please contact Belledonne Communications
* (contact@belledonne-communications.com)
* - C (https://linphone.org/@LINPHONE_STATE@/docs/liblinphone/@LINPHONE_VERSION@/c)
* - C++ (https://linphone.org/@LINPHONE_STATE@/docs/liblinphone/@LINPHONE_VERSION@/c++)
* - Swift (https://linphone.org/@LINPHONE_STATE@/docs/liblinphone/@LINPHONE_VERSION@/swift)
* - Java (https://linphone.org/@LINPHONE_STATE@/docs/liblinphone/@LINPHONE_VERSION@/java)
* - C# (coming soon)
* - Python (coming soon)
*
* Liblinphone is distributed under GPLv3 (https://www.gnu.org/licenses/gpl-3.0.html). Please understand the licencing details before using it!
*
* For any use of this library beyond the rights granted to you by the GPLv3 license, please contact Belledonne Communications (https://www.linphone.org/contact).
*
*
**/
/**
* @page liblinphone_license COPYING
* @include COPYING
*/
/**
* @defgroup initializing Initializing
* @brief Initializing liblinphone.
......@@ -62,7 +58,7 @@
/**
* @defgroup media_parameters Media parameters
* @brief Controlling media parameters.
*
*
* <b>Multicast</b>
*
* Call using rtp multicast addresses are supported for both audio and video with some limitations. Limitations are, no stun, no ice, no encryption.
......@@ -74,7 +70,7 @@
/**
* @defgroup proxies Proxies
* @brief Managing proxies.
*
*
* User registration is controled by #LinphoneProxyConfig settings.<br> Each #LinphoneProxyConfig object can be configured with registration informations
* like \link linphone_proxy_config_set_server_addr() proxy address \endlink , \link linphone_proxy_config_set_identity_address() user id \endlink, \link linphone_proxy_config_expires()
* refresh period \endlink, and so on.
......@@ -123,8 +119,8 @@
*<br> Unregistration or any changes to #LinphoneProxyConfig must be first started by a call to function linphone_proxy_config_edit() and validated by function linphone_proxy_config_done()
*<br> This pseudo code shows how to unregister a user associated to a #LinphoneProxyConfig
*\code
LinphoneProxyConfig* proxy_cfg;
linphone_core_get_default_proxy(lc,&proxy_cfg); /* get default proxy config*/
LinphoneProxyConfig* proxy_cfg;
linphone_core_get_default_proxy(lc,&proxy_cfg); /* get default proxy config*/
linphone_proxy_config_edit(proxy_cfg); /*start editing proxy configuration*/
linphone_proxy_config_enable_register(proxy_cfg,FALSE); /*de-activate registration for this proxy config*/
linphone_proxy_config_done(proxy_cfg); /*initiate REGISTER with expire = 0*/
......@@ -146,7 +142,7 @@
/**
* @defgroup buddy_list Buddy list
* @brief Managing Buddies and buddy list and presence.
*
*
* <b>Buddies and buddy list</b>
* <br>Each buddy is represented by a #LinphoneFriend object created by function linphone_friend_new().
* Buddy configuration parameters like \link linphone_friend_set_addr() sip uri \endlink or \link linphone_friend_set_inc_subscribe_policy() status publication \endlink policy for
......@@ -175,31 +171,31 @@
* linphone_friend_enable_subscribes(my_friend,FALSE); /*disable subscription for this friend*/
* linphone_friend_done(my_friend); /*commit changes triggering an UNSUBSCRIBE message*/
* \endcode
*
*
*
*
* <b> Publishing presence status </b>
* <br>Local presence status can be changed using function linphone_core_set_presence_model() .New status is propagated to all friends \link linphone_core_add_friend() previously added \endlink to #LinphoneCore.
*
*
* <b>Handling incoming subscription request</b>
* <br> New incoming subscription requests are process according to \link linphone_friend_set_inc_subscribe_policy() the incoming subscription policy state \endlink for subscription initiated by \link linphone_core_add_friend() members of the buddy list. \endlink
* <br> For incoming request comming from an unknown buddy, the call back LinphoneCoreVTable.new_subscription_request is invoked.
*
*
* <br> A complete tutorial can be found at : \ref buddy_tutorials "Registration tutorial"
*
*
*
*
**/
/**
* @defgroup chatroom Chatroom
* @brief Chat room and Messaging.
*
*
* <b> Exchanging text messages</b>
* <br> Messages are sent using #LinphoneChatRoom object. First step is to create a \link linphone_core_get_chat_room() chat room \endlink
* from a peer sip uri.
* \code
* LinphoneChatRoom* chat_room = linphone_core_get_chat_room(lc,"sip:joe@sip.linphone.org");
* \endcode
*
*
* <br>Once created, messages are sent using function linphone_chat_room_send_message().
* \code
* linphone_chat_room_send_message(chat_room,"Hello world"); /*sending message*/
......@@ -280,7 +276,7 @@
<br> Liblinphone for IOS natively supports multitasking assuming application follows multitasking guides provided by Apple. First step is to declare application as multitasked. It means adding background mode for both audio and voip to Info.plist file.
<br>
\code
<key>UIBackgroundModes</key>
<key>UIBackgroundModes</key>
<array>
<string>voip</string>
<string>audio</string>
......
############################################################################
# CMakeLists.txt
# Copyright (C) 2017 Belledonne Communications, Grenoble France
#
############################################################################
#
# 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, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
############################################################################
if (ENABLE_DOC)
set(doc_source_dir ${CMAKE_CURRENT_BINARY_DIR}/source)
set(doc_output_dir ${CMAKE_CURRENT_BINARY_DIR}/build)
set(reference_doc_source_dir ${doc_source_dir}/reference)
set(static_documentation_files
guides/android_portability.rst
guides/authentication.rst
guides/buddy_list.rst
guides/call_control.rst
guides/call_logs.rst
guides/call_misc.rst
guides/chatroom.rst
guides/conferencing.rst
guides/event_api.rst
guides/initializing.rst
guides/ios_portability.rst
guides/linphone_address.rst
guides/media_parameters.rst
guides/misc.rst
guides/network_parameters.rst
guides/proxies.rst
index.rst
logo.png
samples/samples.rst
)
configure_file(conf.py.in ${doc_source_dir}/conf.py)
foreach(file ${static_documentation_files})
configure_file(${file} ${doc_source_dir}/${file} COPYONLY)
endforeach(file)
foreach(source ${LINPHONE_C_EXAMPLES_SOURCE})
configure_file(${source} ${doc_source_dir}/samples/ COPYONLY)
endforeach(source)
execute_process(COMMAND ${CMAKE_COMMAND} -E make_directory ${doc_source_dir}/_static ${reference_doc_source_dir})
add_custom_target(sphinx-doc ALL ${PYTHON_EXECUTABLE} '${CMAKE_CURRENT_SOURCE_DIR}/gendoc.py' '${LINPHONE_DOXYGEN_XML_DIR}' -o '${reference_doc_source_dir}'
COMMAND ${PYTHON_EXECUTABLE} -msphinx -M html '${doc_source_dir}' '${doc_output_dir}'
DEPENDS linphone-doc)
install(DIRECTORY ${doc_output_dir}/html/ DESTINATION ${CMAKE_INSTALL_DOCDIR}/${LINPHONE_VERSION})
endif()
{{#hasNamespaceDeclarator}}
.. {{#write_declarator}}namespace{{/write_declarator}}:: {{{namespace}}}
{{#isJava}}
:noindex:
{{/isJava}}
{{/hasNamespaceDeclarator}}
{{#make_chapter}}{{{className}}} class{{/make_chapter}}
.. {{#write_declarator}}class{{/write_declarator}}:: {{{classDeclaration}}}
{{#briefDoc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/briefDoc}}
{{#detailedDoc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/detailedDoc}}
{{{selector}}}
{{#hasNamespaceDeclarator}}
.. {{#write_declarator}}namespace{{/write_declarator}}:: {{{fullClassName}}}
{{#isJava}}
:noindex:
{{/isJava}}
{{/hasNamespaceDeclarator}}
Summary
=======
{{#hasEnums}}
Enums
-----
{{{enumsSummary}}}
{{/hasEnums}}
{{#hasProperties}}
Properties
----------
{{{propertiesSummary}}}
{{/hasProperties}}
{{#hasMethods}}
Methods
-------
{{{instanceMethodsSummary}}}
{{/hasMethods}}
{{#hasClassMethods}}
Class methods
-------------
{{{classMethodsSummary}}}
{{/hasClassMethods}}
Detailed descriptions
=====================
{{#hasEnums}}
Enums
-----
{{#enums}}
{{#make_subsection}}{{{name}}}{{/make_subsection}}
.. {{#write_declarator}}enum{{/write_declarator}}:: {{{declaration}}}
{{#briefDesc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/briefDesc}}
{{{selector}}}
{{#enumerators}}
{{#isNotJava}}
.. {{#write_declarator}}enumerator{{/write_declarator}}:: {{{name}}}
{{/isNotJava}}
{{#isJava}}
**{{{name}}}**
{{/isJava}}
{{#briefDesc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/briefDesc}}
{{{selector}}}
{{/enumerators}}
{{/enums}}
{{/hasEnums}}
{{#hasProperties}}
Properties
----------
{{#properties}}
.. _{{{ref_label}}}:
{{{title}}}
{{#hasNamespaceDeclarator}}
.. {{#write_declarator}}namespace{{/write_declarator}}:: {{{fullClassName}}}
{{#isJava}}
:noindex:
{{/isJava}}
{{/hasNamespaceDeclarator}}
{{#getter}}
.. {{#write_declarator}}method{{/write_declarator}}:: {{{prototype}}}
{{#briefDoc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/briefDoc}}
{{#detailedDoc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/detailedDoc}}
{{{selector}}}
{{/getter}}
{{#setter}}
.. {{#write_declarator}}method{{/write_declarator}}:: {{{prototype}}}
{{#briefDoc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/briefDoc}}
{{#detailedDoc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/detailedDoc}}
{{{selector}}}
{{/setter}}
{{/properties}}
{{/hasProperties}}
{{#hasMethods}}
Public methods
--------------
{{#hasNamespaceDeclarator}}
.. {{#write_declarator}}namespace{{/write_declarator}}:: {{{fullClassName}}}
{{#isJava}}
:noindex:
{{/isJava}}
{{/hasNamespaceDeclarator}}
{{#methods}}
.. {{#write_declarator}}method{{/write_declarator}}:: {{{prototype}}}
{{#briefDoc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/briefDoc}}
{{#detailedDoc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/detailedDoc}}
{{{selector}}}
{{/methods}}
{{/hasMethods}}
{{#hasClassMethods}}
Class methods
-------------
{{#hasNamespaceDeclarator}}
.. {{#write_declarator}}namespace{{/write_declarator}}:: {{{fullClassName}}}
{{#isJava}}
:noindex:
{{/isJava}}
{{/hasNamespaceDeclarator}}
{{#classMethods}}
.. {{#write_declarator}}method{{/write_declarator}}:: static {{{prototype}}}
{{#briefDoc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/briefDoc}}
{{#detailedDoc}}
{{#lines}}
{{{line}}}
{{/lines}}
{{/detailedDoc}}
{{{selector}}}
{{/classMethods}}
{{/hasClassMethods}}
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# Linphone API documentation build configuration file, created by
# sphinx-quickstart on Mon Jun 19 11:58:21 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx_csharp.csharp', 'javasphinx']#, 'swift_domain']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'Linphone Core API'
copyright = '2017, Belledonne Communications SARL'
author = 'Belledonne Communications SARL'
# 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 = '${LINPHONE_MAJOR_VERSION}.${LINPHONE_MINOR_VERSION}'
# The full version, including alpha/beta/rc tags.
release = '${LINPHONE_VERSION}'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'classic'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
html_theme_options = {
'sidebarwidth': '360',
'body_max_width': '100%',
'collapsiblesidebar': 'true'
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Path to the picture to use as logo.
html_logo = 'logo.png'
# Enable html5
html_experimental_html5_writer = True
# Side bar customization
#html_sidebars = {