[libcamera-devel,v3,1/2] Documentation: Introduce sphinx documentation

12 diff mbox series

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@ragnatech.se>
Signed-off-by: Kieran Bingham <kieran.bingham@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

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@ragnatech.se>
> Signed-off-by: Kieran Bingham <kieran.bingham@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-@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')

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@ragnatech.se>
>> Signed-off-by: Kieran Bingham <kieran.bingham@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?

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-@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')
>

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@ragnatech.se>
> >> Signed-off-by: Kieran Bingham <kieran.bingham@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-@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@lists.libcamera.org
> https://lists.libcamera.org/listinfo/libcamera-devel

Hi Kieran,

On Tuesday, 27 November 2018 13:42:37 EET Kieran Bingham wrote:
> On 27/11/2018 01:05, Laurent Pinchart wrote:
> > 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@ragnatech.se>
> >> Signed-off-by: Kieran Bingham <kieran.bingham@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?

I have both python2 and python3 installed. After switching to python3 the 
problem disappears.

> I've added the 'u' and it still builds for me so I'll keep it in there.

Sounds good to me. If we later add more dependencies on python I'm not opposed 
to requiring python3, but if it's just for the conf file, let's keep 
supporting python2.

> > 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-can
> t-i-specify-target-files-with-a-wildcard

Thank you for the pointer. Slightly inconvenient, but not the end of the 
world.

> >> +
> >> +    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-@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 ...

I think spaces after tabs for alignment are fine when using tabs for 
indentation. Mixing tabs and spaces for alignment is what concerns me, as it 
can create problems with alignment-aware files (such as python sources).

> 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

If we use less that 8 spaces for indentation I also prefer using spaces 
instead of tabs.

And according to http://mesonbuild.com/Contributing.html, the preferred style 
for meson.build files uses two spaces for indentation :-( Should we go for 
that, or keep 4 spaces ?

> >> 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')

Hi Laurent,

On 27/11/2018 18:25, Laurent Pinchart wrote:
> Hi Kieran,
> 
<snip>

>>>> +
>>>> +    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-@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 ...
> 
> I think spaces after tabs for alignment are fine when using tabs for 
> indentation. Mixing tabs and spaces for alignment is what concerns me, as it 
> can create problems with alignment-aware files (such as python sources).
> 
>> 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
> 
> If we use less that 8 spaces for indentation I also prefer using spaces 
> instead of tabs.
> 
> And according to http://mesonbuild.com/Contributing.html, the preferred style 
> for meson.build files uses two spaces for indentation :-( Should we go for 
> that, or keep 4 spaces ?

  Eugh ... 2 feels incredibly short for an indent :(

    I would personally prefer 4 ... but if meson.build files already
    have a style guide - I think perhaps we should follow it as much as
    possible

  /me shudders again.

#>>>> 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')
>