{"id":9,"url":"https://patchwork.libcamera.org/api/patches/9/?format=json","web_url":"https://patchwork.libcamera.org/patch/9/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20181122131010.22085-4-kieran.bingham@ideasonboard.com>","date":"2018-11-22T13:10:10","name":"[libcamera-devel,3/3] Documentation: Introduce sphinx documentation","commit_ref":null,"pull_url":null,"state":"accepted","archived":false,"hash":"4bd6887ac0d003f25b4a3db47cf4349d6802f4e1","submitter":{"id":4,"url":"https://patchwork.libcamera.org/api/people/4/?format=json","name":"Kieran Bingham","email":"kieran.bingham@ideasonboard.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/9/mbox/","series":[{"id":4,"url":"https://patchwork.libcamera.org/api/series/4/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=4","date":"2018-11-22T13:10:07","name":"sphinx-documentation and initial CI","version":1,"mbox":"https://patchwork.libcamera.org/series/4/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/9/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/9/checks/","tags":{},"headers":{"Return-Path":"","Received":["from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 5B46C60B12\n\tfor ;\n\tThu, 22 Nov 2018 14:10:16 +0100 (CET)","from localhost.localdomain\n\t(cpc89242-aztw30-2-0-cust488.18-1.cable.virginm.net [86.31.129.233])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id E3763595;\n\tThu, 22 Nov 2018 14:10:15 +0100 (CET)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1542892216;\n\tbh=dqIn31KRR0j5mqx637pG2yFssN7Lwrq/9hegI7z7ZTg=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=THXFn8HjrFemvyI3M6BY+qY67gxLdWBZZ5hKJECRt9nwWc0r2/PvcZ+Hj6FoM2ceO\n\t0HwF2oDAcsV8zbn7DDelgGnbK8zRBWz6S1gaSeqEU2SJ4Oqyw1FfkyDQD58FgX+KPn\n\tOlKCc7Uz+06Sd8EIeCrF9bGAZOqiNnSS9Hd6p3Uw=","From":"Kieran Bingham ","To":"LibCamera Devel ","Date":"Thu, 22 Nov 2018 13:10:10 +0000","Message-Id":"<20181122131010.22085-4-kieran.bingham@ideasonboard.com>","X-Mailer":"git-send-email 2.17.1","In-Reply-To":"<20181122131010.22085-1-kieran.bingham@ideasonboard.com>","References":"<20181122131010.22085-1-kieran.bingham@ideasonboard.com>","Subject":"[libcamera-devel] [PATCH 3/3] Documentation: Introduce sphinx\n\tdocumentation","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.23","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","X-List-Received-Date":"Thu, 22 Nov 2018 13:10:16 -0000"},"content":"Utilise sphinx-build to generate documentation in HTML form, and\npopulate with some initial content.\n\nAn initial conf.py is generated from sphinx-quickstart and answering\ninitial questions.\n\nSigned-off-by: Kieran Bingham \n---\n .gitlab-ci.yml | 2 +-\n Documentation/Makefile | 19 +++++\n Documentation/conf.py | 173 ++++++++++++++++++++++++++++++++++++++\n Documentation/hacking.rst | 42 +++++++++\n Documentation/index.rst | 36 ++++++++\n Documentation/meson.build | 20 +++++\n meson.build | 6 ++\n 7 files changed, 297 insertions(+), 1 deletion(-)\n create mode 100644 Documentation/Makefile\n create mode 100644 Documentation/conf.py\n create mode 100644 Documentation/hacking.rst\n create mode 100644 Documentation/index.rst\n create mode 100644 Documentation/meson.build","diff":"diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml\nindex 8b4b4b12d368..d7d41425dd8e 100644\n--- a/.gitlab-ci.yml\n+++ b/.gitlab-ci.yml\n@@ -3,7 +3,7 @@ image: gcc\n build:\n stage: build\n before_script:\n- - apt update && apt -y install meson\n+ - apt update && apt -y install meson python3-sphinx\n script:\n - mkdir libcamera && cd libcamera && meson .. && ninja\n - ninja test\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nnew file mode 100644\nindex 000000000000..298ea9e213e8\n--- /dev/null\n+++ b/Documentation/Makefile\n@@ -0,0 +1,19 @@\n+# Minimal makefile for Sphinx documentation\n+#\n+\n+# You can set these variables from the command line.\n+SPHINXOPTS =\n+SPHINXBUILD = sphinx-build\n+SOURCEDIR = .\n+BUILDDIR = _build\n+\n+# Put it first so that \"make\" without argument is like \"make help\".\n+help:\n+\t@$(SPHINXBUILD) -M help \"$(SOURCEDIR)\" \"$(BUILDDIR)\" $(SPHINXOPTS) $(O)\n+\n+.PHONY: help Makefile\n+\n+# Catch-all target: route all unknown targets to Sphinx using the new\n+# \"make mode\" option. $(O) is meant as a shortcut for $(SPHINXOPTS).\n+%: Makefile\n+\t@$(SPHINXBUILD) -M $@ \"$(SOURCEDIR)\" \"$(BUILDDIR)\" $(SPHINXOPTS) $(O)\n\\ No newline at end of file\ndiff --git a/Documentation/conf.py b/Documentation/conf.py\nnew file mode 100644\nindex 000000000000..70d4e72c6902\n--- /dev/null\n+++ b/Documentation/conf.py\n@@ -0,0 +1,173 @@\n+# -*- coding: utf-8 -*-\n+#\n+# Configuration file for the Sphinx documentation builder.\n+#\n+# This file does only contain a selection of the most common options. For a\n+# full list see the documentation:\n+# http://www.sphinx-doc.org/en/master/config\n+\n+# -- Path setup --------------------------------------------------------------\n+\n+# If extensions (or modules to document with autodoc) are in another directory,\n+# add these directories to sys.path here. If the directory is relative to the\n+# documentation root, use os.path.abspath to make it absolute, like shown here.\n+#\n+# import os\n+# import sys\n+# sys.path.insert(0, os.path.abspath('.'))\n+\n+\n+# -- Project information -----------------------------------------------------\n+\n+project = 'LibCamera'\n+copyright = '2018, Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Soderlund'\n+author = 'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Soderlund'\n+\n+# The short X.Y version\n+version = ''\n+# The full version, including alpha/beta/rc tags\n+release = '0.1'\n+\n+\n+# -- General configuration ---------------------------------------------------\n+\n+# If your documentation needs a minimal Sphinx version, state it here.\n+#\n+# needs_sphinx = '1.0'\n+\n+# Add any Sphinx extension module names here, as strings. They can be\n+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n+# ones.\n+extensions = [\n+]\n+\n+# Add any paths that contain templates here, relative to this directory.\n+templates_path = ['_templates']\n+\n+# The suffix(es) of source filenames.\n+# You can specify multiple suffix as a list of string:\n+#\n+# source_suffix = ['.rst', '.md']\n+source_suffix = '.rst'\n+\n+# The master toctree document.\n+master_doc = 'index'\n+\n+# The language for content autogenerated by Sphinx. Refer to documentation\n+# for a list of supported languages.\n+#\n+# This is also used if you do content translation via gettext catalogs.\n+# Usually you set \"language\" from the command line for these cases.\n+language = None\n+\n+# List of patterns, relative to source directory, that match files and\n+# directories to ignore when looking for source files.\n+# This pattern also affects html_static_path and html_extra_path.\n+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']\n+\n+# The name of the Pygments (syntax highlighting) style to use.\n+pygments_style = None\n+\n+\n+# -- Options for HTML output -------------------------------------------------\n+\n+# The theme to use for HTML and HTML Help pages. See the documentation for\n+# a list of builtin themes.\n+#\n+html_theme = 'alabaster'\n+\n+# Theme options are theme-specific and customize the look and feel of a theme\n+# further. For a list of options available for each theme, see the\n+# documentation.\n+#\n+# html_theme_options = {}\n+\n+# Add any paths that contain custom static files (such as style sheets) here,\n+# relative to this directory. They are copied after the builtin static files,\n+# so a file named \"default.css\" will overwrite the builtin \"default.css\".\n+html_static_path = ['_static']\n+\n+# Custom sidebar templates, must be a dictionary that maps document names\n+# to template names.\n+#\n+# The default sidebars (for documents that don't match any pattern) are\n+# defined by theme itself. Builtin themes are using these templates by\n+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',\n+# 'searchbox.html']``.\n+#\n+# html_sidebars = {}\n+\n+\n+# -- Options for HTMLHelp output ---------------------------------------------\n+\n+# Output file base name for HTML help builder.\n+htmlhelp_basename = 'LibCameradoc'\n+\n+\n+# -- Options for LaTeX output ------------------------------------------------\n+\n+latex_elements = {\n+ # The paper size ('letterpaper' or 'a4paper').\n+ #\n+ # 'papersize': 'letterpaper',\n+\n+ # The font size ('10pt', '11pt' or '12pt').\n+ #\n+ # 'pointsize': '10pt',\n+\n+ # Additional stuff for the LaTeX preamble.\n+ #\n+ # 'preamble': '',\n+\n+ # Latex figure (float) alignment\n+ #\n+ # 'figure_align': 'htbp',\n+}\n+\n+# Grouping the document tree into LaTeX files. List of tuples\n+# (source start file, target name, title,\n+# author, documentclass [howto, manual, or own class]).\n+latex_documents = [\n+ (master_doc, 'LibCamera.tex', 'LibCamera Documentation',\n+ 'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Soderlund', 'manual'),\n+]\n+\n+\n+# -- Options for manual page output ------------------------------------------\n+\n+# One entry per manual page. List of tuples\n+# (source start file, name, description, authors, manual section).\n+man_pages = [\n+ (master_doc, 'libcamera', 'LibCamera Documentation',\n+ [author], 1)\n+]\n+\n+\n+# -- Options for Texinfo output ----------------------------------------------\n+\n+# Grouping the document tree into Texinfo files. List of tuples\n+# (source start file, target name, title, author,\n+# dir menu entry, description, category)\n+texinfo_documents = [\n+ (master_doc, 'LibCamera', 'LibCamera Documentation',\n+ author, 'LibCamera', 'One line description of project.',\n+ 'Miscellaneous'),\n+]\n+\n+\n+# -- Options for Epub output -------------------------------------------------\n+\n+# Bibliographic Dublin Core info.\n+epub_title = project\n+\n+# The unique identifier of the text. This can be a ISBN number\n+# or the project homepage.\n+#\n+# epub_identifier = ''\n+\n+# A unique identification for the text.\n+#\n+# epub_uid = ''\n+\n+# A list of files that should not be packed into the epub file.\n+epub_exclude_files = ['search.html']\n\\ No newline at end of file\ndiff --git a/Documentation/hacking.rst b/Documentation/hacking.rst\nnew file mode 100644\nindex 000000000000..f65381e8f290\n--- /dev/null\n+++ b/Documentation/hacking.rst\n@@ -0,0 +1,42 @@\n+Hacking and Development\n+=======================\n+\n+libcamera is developed as a free software project and welcomes contributors.\n+Whether you would like to help with coding, documentation, testing, proposing\n+new features, or just discussing the project with the community, you can join\n+our official public communication hannels, or simply check out the code.\n+Mailing List\n+\n+We use a public mailing list as our main mean of communication. You can find\n+subscription information and the messages archive on the libcamera-devel list\n+information page.\n+\n+IRC Channel\n+-----------\n+\n+For informal and real time discussions, our IRC channel on Freenode is open to\n+the public. Point your IRC client to #libcamera to say hello, or use the `WebChat`_.\n+\n+.. _WebChat: https://webchat.freenode.net/?channels=%23libcamera&uio=d4\n+\n+Source Code\n+-----------\n+\n+libcamera is in early stages of development, no releases are available yet. The\n+source code is available from the project's git tree, hosted by LinuxTV.\n+\n+ $ git clone git://linuxtv.org/libcamera.git\n+\n+Documentation\n+-------------\n+\n+Project documentation is created using `Sphinx`_. Source level documentation\n+is currently planned to utilise Doxygen integration. Please use this in your\n+development.\n+\n+Sphinx integration with Doxygen will be with either `Breathe`_ or `Exhale`_\n+depending upon which system works best\n+\n+.. _Sphinx: http://www.sphinx-doc.org\n+.. _Breathe: https://breathe.readthedocs.io/en/latest/\n+.. _Exhale: https://exhale.readthedocs.io/en/latest/\ndiff --git a/Documentation/index.rst b/Documentation/index.rst\nnew file mode 100644\nindex 000000000000..36708af15c2c\n--- /dev/null\n+++ b/Documentation/index.rst\n@@ -0,0 +1,36 @@\n+.. LibCamera documentation master file, created by\n+ sphinx-quickstart on Mon Nov 19 22:09:29 2018.\n+ You can adapt this file completely to your liking, but it should at least\n+ contain the root `toctree` directive.\n+\n+LibCamera abstraction library\n+=============================\n+\n+Cameras are complex devices that need heavy hardware image processing\n+operations. Control of the processing is based on advanced algorithms that must\n+run on a programmable processor. This has traditionally been implemented in a\n+dedicated MCU in the camera, but in embedded devices algorithms have been moved\n+to the main CPU to save cost. Blurring the boundary between camera devices and\n+Linux often left the user with no other option than a vendor-specific\n+closed-source solution.\n+\n+To address this problem the Linux media community has very recently started\n+collaboration with the industry to develop a camera stack that will be\n+open-source-friendly while still protecting vendor core IP. libcamera was born\n+out of that collaboration and will offer modern camera support to Linux-based\n+systems, including traditional Linux distributions, ChromeOS and Android.\n+\n+\n+.. toctree::\n+ :maxdepth: 2\n+ :caption: Contents:\n+\n+ hacking\n+\n+\n+\n+Indices and tables\n+==================\n+\n+* :ref:`genindex`\n+* :ref:`search`\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nnew file mode 100644\nindex 000000000000..5ab04479d3fb\n--- /dev/null\n+++ b/Documentation/meson.build\n@@ -0,0 +1,20 @@\n+sphinx = find_program('sphinx-build-3', required: false)\n+if not sphinx.found()\n+ sphinx = find_program('sphinx-build', required: false)\n+endif\n+\n+if sphinx.found()\n+ docs_sources = [\n+\t'hacking.rst',\n+\t'index.rst',\n+ ]\n+\n+ custom_target('en user documentation',\n+\t\t command: [sphinx, '-W', '-b', 'html', meson.current_source_dir(), '@OUTPUT@'],\n+\t\t input: docs_sources,\n+\t\t output: 'en',\n+\t\t build_by_default: true)\n+\n+ install_subdir(meson.current_build_dir() + '/en',\n+\t\t install_dir: 'share/doc/libcamera-@0@/user'.format(api_version))\n+endif\ndiff --git a/meson.build b/meson.build\nindex 4b3d528c8932..434aa557b8a1 100644\n--- a/meson.build\n+++ b/meson.build\n@@ -2,8 +2,14 @@ project('libcamera - supporting complex camera pipelines', 'c', 'cpp',\n version : '0.1',\n license : 'LGPL 2.1+')\n \n+# TODO: Extract this from project.version.\n+#\tIdeally the version at Documentation/conf.py should be\n+#\tgenerated from this too.\n+api_version = '0.1'\n+\n inc = include_directories('include')\n \n+subdir('Documentation')\n subdir('lib')\n subdir('test')\n subdir('utils')\n","prefixes":["libcamera-devel","3/3"]}