[libcamera-devel] [PATCH 3/3] Documentation: Introduce sphinx documentation

[Kieran Bingham]

On 22/11/2018 13:10, Kieran Bingham wrote:
> Utilise sphinx-build to generate documentation in HTML form, and
> populate with some initial content.
> 
> An initial conf.py is generated from sphinx-quickstart and answering
> initial questions.
> 
> Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
> ---
>  .gitlab-ci.yml            |   2 +-
>  Documentation/Makefile    |  19 +++++
>  Documentation/conf.py     | 173 ++++++++++++++++++++++++++++++++++++++
>  Documentation/hacking.rst |  42 +++++++++
>  Documentation/index.rst   |  36 ++++++++
>  Documentation/meson.build |  20 +++++
>  meson.build               |   6 ++
>  7 files changed, 297 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/Makefile
>  create mode 100644 Documentation/conf.py
>  create mode 100644 Documentation/hacking.rst
>  create mode 100644 Documentation/index.rst
>  create mode 100644 Documentation/meson.build
> 
> diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
> index 8b4b4b12d368..d7d41425dd8e 100644
> --- a/.gitlab-ci.yml
> +++ b/.gitlab-ci.yml
> @@ -3,7 +3,7 @@ image: gcc
>  build:
>    stage: build
>    before_script:
> -    - apt update && apt -y install meson
> +    - apt update && apt -y install meson python3-sphinx
>    script:
>      - mkdir libcamera && cd libcamera && meson .. && ninja
>      - ninja test
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> new file mode 100644
> index 000000000000..298ea9e213e8
> --- /dev/null
> +++ b/Documentation/Makefile
> @@ -0,0 +1,19 @@
> +# Minimal makefile for Sphinx documentation
> +#
> +
> +# You can set these variables from the command line.
> +SPHINXOPTS    =
> +SPHINXBUILD   = sphinx-build
> +SOURCEDIR     = .
> +BUILDDIR      = _build
> +
> +# Put it first so that "make" without argument is like "make help".
> +help:
> +	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
> +
> +.PHONY: help Makefile
> +
> +# Catch-all target: route all unknown targets to Sphinx using the new
> +# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
> +%: Makefile
> +	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
> \ No newline at end of file
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> new file mode 100644
> index 000000000000..70d4e72c6902
> --- /dev/null
> +++ b/Documentation/conf.py
> @@ -0,0 +1,173 @@
> +# -*- coding: utf-8 -*-
> +#
> +# Configuration file for the Sphinx documentation builder.
> +#
> +# This file does only contain a selection of the most common options. For a
> +# full list see the documentation:
> +# http://www.sphinx-doc.org/en/master/config
> +
> +# -- Path setup --------------------------------------------------------------
> +
> +# 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('.'))
> +
> +
> +# -- Project information -----------------------------------------------------
> +
> +project = 'LibCamera'
> +copyright = '2018, Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Soderlund'
> +author = 'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Soderlund'
> +
> +# The short X.Y version
> +version = ''
> +# The full version, including alpha/beta/rc tags
> +release = '0.1'
> +
> +
> +# -- 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 = [
> +]
> +
> +# 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'
> +
> +# 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 pattern also affects html_static_path and html_extra_path.
> +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
> +
> +# The name of the Pygments (syntax highlighting) style to use.
> +pygments_style = None
> +
> +
> +# -- 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 = 'alabaster'
> +
> +# 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 = {}
> +
> +# 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']
> +
> +# Custom sidebar templates, must be a dictionary that maps document names
> +# to template names.
> +#
> +# The default sidebars (for documents that don't match any pattern) are
> +# defined by theme itself.  Builtin themes are using these templates by
> +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
> +# 'searchbox.html']``.
> +#
> +# html_sidebars = {}
> +
> +
> +# -- Options for HTMLHelp output ---------------------------------------------
> +
> +# Output file base name for HTML help builder.
> +htmlhelp_basename = 'LibCameradoc'
> +
> +
> +# -- Options for LaTeX output ------------------------------------------------
> +
> +latex_elements = {
> +    # The paper size ('letterpaper' or 'a4paper').
> +    #
> +    # 'papersize': 'letterpaper',
> +
> +    # The font size ('10pt', '11pt' or '12pt').
> +    #
> +    # 'pointsize': '10pt',
> +
> +    # Additional stuff for the LaTeX preamble.
> +    #
> +    # 'preamble': '',
> +
> +    # Latex figure (float) alignment
> +    #
> +    # 'figure_align': 'htbp',
> +}
> +
> +# Grouping the document tree into LaTeX files. List of tuples
> +# (source start file, target name, title,
> +#  author, documentclass [howto, manual, or own class]).
> +latex_documents = [
> +    (master_doc, 'LibCamera.tex', 'LibCamera Documentation',
> +     'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Soderlund', 'manual'),
> +]
> +
> +
> +# -- Options for manual page output ------------------------------------------
> +
> +# One entry per manual page. List of tuples
> +# (source start file, name, description, authors, manual section).
> +man_pages = [
> +    (master_doc, 'libcamera', 'LibCamera Documentation',
> +     [author], 1)
> +]
> +
> +
> +# -- Options for Texinfo output ----------------------------------------------
> +
> +# Grouping the document tree into Texinfo files. List of tuples
> +# (source start file, target name, title, author,
> +#  dir menu entry, description, category)
> +texinfo_documents = [
> +    (master_doc, 'LibCamera', 'LibCamera Documentation',
> +     author, 'LibCamera', 'One line description of project.',
> +     'Miscellaneous'),
> +]
> +
> +
> +# -- Options for Epub output -------------------------------------------------
> +
> +# Bibliographic Dublin Core info.
> +epub_title = project
> +
> +# The unique identifier of the text. This can be a ISBN number
> +# or the project homepage.
> +#
> +# epub_identifier = ''
> +
> +# A unique identification for the text.
> +#
> +# epub_uid = ''
> +
> +# A list of files that should not be packed into the epub file.
> +epub_exclude_files = ['search.html']
> \ No newline at end of file
> diff --git a/Documentation/hacking.rst b/Documentation/hacking.rst
> new file mode 100644
> index 000000000000..f65381e8f290
> --- /dev/null
> +++ b/Documentation/hacking.rst
> @@ -0,0 +1,42 @@
> +Hacking and Development
> +=======================
> +
> +libcamera is developed as a free software project and welcomes contributors.
> +Whether you would like to help with coding, documentation, testing, proposing
> +new features, or just discussing the project with the community, you can join
> +our official public communication hannels, or simply check out the code.
> +Mailing List
> +
> +We use a public mailing list as our main mean of communication. You can find
> +subscription information and the messages archive on the libcamera-devel list
> +information page.
> +
> +IRC Channel
> +-----------
> +
> +For informal and real time discussions, our IRC channel on Freenode is open to
> +the public. Point your IRC client to #libcamera to say hello, or use the `WebChat`_.
> +
> +.. _WebChat: https://webchat.freenode.net/?channels=%23libcamera&uio=d4
> +
> +Source Code
> +-----------
> +
> +libcamera is in early stages of development, no releases are available yet. The
> +source code is available from the project's git tree, hosted by LinuxTV.
> +
> +  $ git clone git://linuxtv.org/libcamera.git
> +
> +Documentation
> +-------------
> +
> +Project documentation is created using `Sphinx`_.  Source level documentation
> +is currently planned to utilise Doxygen integration.  Please use this in your
> +development.
> +
> +Sphinx integration with Doxygen will be with either `Breathe`_ or `Exhale`_
> +depending upon which system works best
> +
> +.. _Sphinx: http://www.sphinx-doc.org
> +.. _Breathe: https://breathe.readthedocs.io/en/latest/
> +.. _Exhale: https://exhale.readthedocs.io/en/latest/
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> new file mode 100644
> index 000000000000..36708af15c2c
> --- /dev/null
> +++ b/Documentation/index.rst
> @@ -0,0 +1,36 @@

<KB:start>

> +.. LibCamera documentation master file, created by
> +   sphinx-quickstart on Mon Nov 19 22:09:29 2018.
> +   You can adapt this file completely to your liking, but it should at least
> +   contain the root `toctree` directive.
> +

Isn't it great when you see something just as you hit 'send'.

This comment will be removed.

<KB:End>


> +LibCamera abstraction library
> +=============================
> +
> +Cameras are complex devices that need heavy hardware image processing
> +operations. Control of the processing is based on advanced algorithms that must
> +run on a programmable processor. This has traditionally been implemented in a
> +dedicated MCU in the camera, but in embedded devices algorithms have been moved
> +to the main CPU to save cost. Blurring the boundary between camera devices and
> +Linux often left the user with no other option than a vendor-specific
> +closed-source solution.
> +
> +To address this problem the Linux media community has very recently started
> +collaboration with the industry to develop a camera stack that will be
> +open-source-friendly while still protecting vendor core IP. libcamera was born
> +out of that collaboration and will offer modern camera support to Linux-based
> +systems, including traditional Linux distributions, ChromeOS and Android.
> +
> +
> +.. toctree::
> +   :maxdepth: 2
> +   :caption: Contents:
> +
> +   hacking
> +

As will this extra blank line.

> +
> +
> +Indices and tables
> +==================
> +
> +* :ref:`genindex`
> +* :ref:`search`
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> new file mode 100644
> index 000000000000..5ab04479d3fb
> --- /dev/null
> +++ b/Documentation/meson.build
> @@ -0,0 +1,20 @@
> +sphinx = find_program('sphinx-build-3', required: false)
> +if not sphinx.found()
> +    sphinx = find_program('sphinx-build', required: false)
> +endif
> +
> +if sphinx.found()
> +    docs_sources = [
> +	'hacking.rst',
> +	'index.rst',
> +    ]
> +
> +    custom_target('en user documentation',
> +		  command: [sphinx, '-W', '-b', 'html', meson.current_source_dir(), '@OUTPUT@'],
> +		  input: docs_sources,
> +		  output: 'en',
> +		  build_by_default: true)
> +
> +    install_subdir(meson.current_build_dir() + '/en',
> +		  install_dir: 'share/doc/libcamera- at 0@/user'.format(api_version))
> +endif
> diff --git a/meson.build b/meson.build
> index 4b3d528c8932..434aa557b8a1 100644
> --- a/meson.build
> +++ b/meson.build
> @@ -2,8 +2,14 @@ project('libcamera - supporting complex camera pipelines', 'c', 'cpp',
>    version : '0.1',
>    license : 'LGPL 2.1+')
>  
> +# TODO: Extract this from project.version.
> +#	Ideally the version at Documentation/conf.py should be
> +#	generated from this too.
> +api_version = '0.1'
> +
>  inc = include_directories('include')
>  
> +subdir('Documentation')
>  subdir('lib')
>  subdir('test')
>  subdir('utils')
> 

-- 
Regards
--
Kieran