[libcamera-devel] [PATCH v3 1/2] Documentation: Introduce sphinx documentation
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Tue Nov 27 02:05:47 CET 2018
Hi Kieran,
Thank you for the patch.
On Monday, 26 November 2018 13:11:47 EET 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.
>
> Reviewed-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>
> Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
>
> ---
>
> v3:
> - Rename hacking to contributing
> - LibCamera -> libcamera
> - Fix ö usage
> - Add conf.py to meson.build to catch dependency
> - Add .keep_empty files to maintain source structures
> - Remove 'user' level hierarchy
> - Simplify 'documentation' install target description
> - Install html docs to html directory
>
> Documentation/_static/.keep_empty | 0
> Documentation/_templates/.keep_empty | 0
> Documentation/conf.py | 173 +++++++++++++++++++++++++++
> Documentation/contributing.rst | 46 +++++++
> Documentation/index.rst | 30 +++++
> Documentation/meson.build | 21 ++++
> meson.build | 6 +
> 7 files changed, 276 insertions(+)
> create mode 100644 Documentation/_static/.keep_empty
> create mode 100644 Documentation/_templates/.keep_empty
> create mode 100644 Documentation/conf.py
> create mode 100644 Documentation/contributing.rst
> create mode 100644 Documentation/index.rst
> create mode 100644 Documentation/meson.build
>
> diff --git a/Documentation/_static/.keep_empty
> b/Documentation/_static/.keep_empty new file mode 100644
> index 000000000000..e69de29bb2d1
> diff --git a/Documentation/_templates/.keep_empty
> b/Documentation/_templates/.keep_empty new file mode 100644
> index 000000000000..e69de29bb2d1
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> new file mode 100644
> index 000000000000..dada1eba2761
> --- /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
> Söderlund'
Trying to build the documentation produces the following error:
[3/3] Generating documentation with a custom command.
FAILED: Documentation/html
/usr/bin/sphinx-build -W -b html /home/laurent/src/iob/oss/libcamera/
libcamera.git/Documentation Documentation/html
Running Sphinx v1.7.5
Warning, treated as error:
the config value 'copyright' is set to a string with non-ASCII characters;
this can lead to Unicode errors occurring. Please use Unicode strings, e.g.
u'Content'.
ninja: build stopped: subcommand failed.
In order to duplicate the list of names, how about setting
copyright = '2018, the libcamera documentation authors'
> +author = 'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Söderlund'
This requires the u prefix.
> +# 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 Söderlund',
And the string here can be replaced with author. With these changes, the
documentation compiles.
> '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']
> diff --git a/Documentation/contributing.rst b/Documentation/contributing.rst
> new file mode 100644
> index 000000000000..dd6f5efa6872
> --- /dev/null
> +++ b/Documentation/contributing.rst
> @@ -0,0 +1,46 @@
> +Contributing
> +============
> +
> +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 channels, or
> simply check out the code. +
> +Mailing List
> +------------
> +
> +We use a public mailing list as our main means of communication. You can
> find +subscription information and the messages archive on the
> `libcamera-devel`_ +list information page.
> +
> +.. _libcamera-devel: https://lists.libcamera.org/listinfo/libcamera-devel
> +
> +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, and 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..c9b7c1cd0fda
> --- /dev/null
> +++ b/Documentation/index.rst
> @@ -0,0 +1,30 @@
> +libcamera
> +=========
> +
> +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:
> +
> + contributing
> +
> +
> +Indices and tables
> +==================
> +
> +* :ref:`genindex`
> +* :ref:`search`
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> new file mode 100644
> index 000000000000..7f0afd7d3a58
> --- /dev/null
> +++ b/Documentation/meson.build
> @@ -0,0 +1,21 @@
> +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 = [
> + 'conf.py',
> + 'contributing.rst',
> + 'index.rst',
> + ]
I assume there will be a way to wildcard *.rst later. No need to fix it right
now.
> +
> + custom_target('documentation',
> + command: [sphinx, '-W', '-b', 'html', meson.current_source_dir(),
> '@OUTPUT@'], + input: docs_sources,
> + output: 'html',
> + build_by_default: true)
> +
> + install_subdir(meson.current_build_dir() + '/html',
> + install_dir: 'share/doc/libcamera- at 0@'.format(api_version))
> +endif
Mixing spaces and tabs for indentations worries me. What's your opinion ?
> 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,
Laurent Pinchart
More information about the libcamera-devel
mailing list