[libcamera-devel] [PATCH v3 1/2] Documentation: Introduce sphinx documentation
jacopo mondi
jacopo at jmondi.org
Tue Nov 27 12:59:36 CET 2018
Hi Kieran,
On Tue, Nov 27, 2018 at 11:42:37AM +0000, Kieran Bingham wrote:
> Hi Laurent,
>
> On 27/11/2018 01:05, Laurent Pinchart wrote:
> > 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
>
> Hrm ...
>
> I'm running with a slightly different version of sphinx... :
> Running Sphinx v1.8.2
>
> > 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'.
>
> But I don't get this of course.
>
> I wonder if this is a python or sphinx warning?
>
> Just tested on my gitlab-ci as well which is using Sphinx v1.7.4
>
> I believe that environment has only python3 and no warning, so perhaps
> can I infer that you have only python2, and that is the root of this
> warning?
It breaks for me as well, so let me know if I can help debug the
issue.
>
> I've added the 'u' and it still builds for me so I'll keep it in there.
>
>
> > ninja: build stopped: subcommand failed.
> >
> > In order to duplicate the list of names, how about setting
> >
> > copyright = '2018, the libcamera documentation authors'
>
> Sure, It was pasted by the quickstart.
>
>
> >> +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.
>
> This is autogenerated by sphinx-quickstart, but I see below in man_pages
> they reference [author] instead of pasting it.
>
> I wonder why they were inconsistent. Anyway - that's an upstream issue.
> I'll just fix locally here.
>
>
> >
> >> '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.
>
> Nope...
>
> https://github.com/mesonbuild/meson/blob/master/docs/markdown/FAQ.md#why-cant-i-specify-target-files-with-a-wildcard
>
>
> >
> >> +
> >> + 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 ?
>
> This was supposed to align the content to the brackets.
> Just as we do in in the kernel ...
>
> It seems that the meson developers do not like tabs at all:
> https://mesonbuild.com/Style-guide.html:
>
> > Tabs or spaces?
> >
> > Always spaces.
>
> I'll change
>
>
> >> 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
> _______________________________________________
> libcamera-devel mailing list
> libcamera-devel at lists.libcamera.org
> https://lists.libcamera.org/listinfo/libcamera-devel
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <https://lists.libcamera.org/pipermail/libcamera-devel/attachments/20181127/d21a61c8/attachment-0001.sig>
More information about the libcamera-devel
mailing list