[libcamera-devel] [PATCH v2] Documentation: Introduce sphinx documentation

[Kieran Bingham]

Hi Niklas,

Thank you for the review,

On 23/11/2018 13:19, Niklas Söderlund wrote:
> Hi Kieran,
> 
> Thanks for your patch.
> 
> On 2018-11-22 16:58:52 +0000, Kieran Bingham wrote:
>> Utilise sphinx-build to generate documentation in HTML form, and
>> populate with some initial content.
>>
>> An initial conf.py is generated from sphinx-quickstart and answering
>> initial questions.
>>
>> Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
>>
>> ---
>> v2:
>>  - Fix spelling in hacking.rst
>>  - Remove autogenerated comments at index.rst
>>  - Fix whitespaces
>>  - Remove autogenerated Makefile
>>  - Fix typos and grammar
>>
>>  Documentation/conf.py     | 173 ++++++++++++++++++++++++++++++++++++++
>>  Documentation/hacking.rst |  42 +++++++++
>>  Documentation/index.rst   |  30 +++++++
>>  Documentation/meson.build |  20 +++++
>>  meson.build               |   6 ++
>>  5 files changed, 271 insertions(+)
>>  create mode 100644 Documentation/conf.py
>>  create mode 100644 Documentation/hacking.rst
>>  create mode 100644 Documentation/index.rst
>>  create mode 100644 Documentation/meson.build
>>
>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>> new file mode 100644
>> index 000000000000..70d4e72c6902
>> --- /dev/null
>> +++ b/Documentation/conf.py
>> @@ -0,0 +1,173 @@
>> +# -*- coding: utf-8 -*-
>> +#
>> +# Configuration file for the Sphinx documentation builder.
>> +#
>> +# This file does only contain a selection of the most common options. For a
>> +# full list see the documentation:
>> +# http://www.sphinx-doc.org/en/master/config
>> +
>> +# -- Path setup --------------------------------------------------------------
>> +
>> +# If extensions (or modules to document with autodoc) are in another directory,
>> +# add these directories to sys.path here. If the directory is relative to the
>> +# documentation root, use os.path.abspath to make it absolute, like shown here.
>> +#
>> +# import os
>> +# import sys
>> +# sys.path.insert(0, os.path.abspath('.'))
>> +
>> +
>> +# -- Project information -----------------------------------------------------
>> +
>> +project = 'LibCamera'
>> +copyright = '2018, Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Soderlund'
>> +author = 'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Soderlund'
> 
> My pretty döts seems to me missing :-)

I have no idea how to generate those on my keyboard...

Fortunately - you've now given me a character I can copy and paste.
 (yes, of course it was already in my e-mail client)

Perhaps I was giving you a chance to increase your patch count with a
fixup patch later ;-)

> 
>> +
>> +# The short X.Y version
>> +version = ''
>> +# The full version, including alpha/beta/rc tags
>> +release = '0.1'
>> +
>> +
>> +# -- General configuration ---------------------------------------------------
>> +
>> +# If your documentation needs a minimal Sphinx version, state it here.
>> +#
>> +# needs_sphinx = '1.0'
>> +
>> +# Add any Sphinx extension module names here, as strings. They can be
>> +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
>> +# ones.
>> +extensions = [
>> +]
>> +
>> +# Add any paths that contain templates here, relative to this directory.
>> +templates_path = ['_templates']
>> +
>> +# The suffix(es) of source filenames.
>> +# You can specify multiple suffix as a list of string:
>> +#
>> +# source_suffix = ['.rst', '.md']
>> +source_suffix = '.rst'
>> +
>> +# The master toctree document.
>> +master_doc = 'index'
>> +
>> +# The language for content autogenerated by Sphinx. Refer to documentation
>> +# for a list of supported languages.
>> +#
>> +# This is also used if you do content translation via gettext catalogs.
>> +# Usually you set "language" from the command line for these cases.
>> +language = None
>> +
>> +# List of patterns, relative to source directory, that match files and
>> +# directories to ignore when looking for source files.
>> +# This pattern also affects html_static_path and html_extra_path.
>> +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
>> +
>> +# The name of the Pygments (syntax highlighting) style to use.
>> +pygments_style = None
>> +
>> +
>> +# -- Options for HTML output -------------------------------------------------
>> +
>> +# The theme to use for HTML and HTML Help pages.  See the documentation for
>> +# a list of builtin themes.
>> +#
>> +html_theme = 'alabaster'
>> +
>> +# Theme options are theme-specific and customize the look and feel of a theme
>> +# further.  For a list of options available for each theme, see the
>> +# documentation.
>> +#
>> +# html_theme_options = {}
>> +
>> +# Add any paths that contain custom static files (such as style sheets) here,
>> +# relative to this directory. They are copied after the builtin static files,
>> +# so a file named "default.css" will overwrite the builtin "default.css".
>> +html_static_path = ['_static']
>> +
>> +# Custom sidebar templates, must be a dictionary that maps document names
>> +# to template names.
>> +#
>> +# The default sidebars (for documents that don't match any pattern) are
>> +# defined by theme itself.  Builtin themes are using these templates by
>> +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
>> +# 'searchbox.html']``.
>> +#
>> +# html_sidebars = {}
>> +
>> +
>> +# -- Options for HTMLHelp output ---------------------------------------------
>> +
>> +# Output file base name for HTML help builder.
>> +htmlhelp_basename = 'LibCameradoc'
>> +
>> +
>> +# -- Options for LaTeX output ------------------------------------------------
>> +
>> +latex_elements = {
>> +    # The paper size ('letterpaper' or 'a4paper').
>> +    #
>> +    # 'papersize': 'letterpaper',
>> +
>> +    # The font size ('10pt', '11pt' or '12pt').
>> +    #
>> +    # 'pointsize': '10pt',
>> +
>> +    # Additional stuff for the LaTeX preamble.
>> +    #
>> +    # 'preamble': '',
>> +
>> +    # Latex figure (float) alignment
>> +    #
>> +    # 'figure_align': 'htbp',
>> +}
>> +
>> +# Grouping the document tree into LaTeX files. List of tuples
>> +# (source start file, target name, title,
>> +#  author, documentclass [howto, manual, or own class]).
>> +latex_documents = [
>> +    (master_doc, 'LibCamera.tex', 'LibCamera Documentation',
>> +     'Kieran Bingham, Jacopo Mondi, Laurent Pinchart, Niklas Soderlund', 'manual'),
> 
> :-)
> 

I'll update here as well.


>> +]
>> +
>> +
>> +# -- Options for manual page output ------------------------------------------
>> +
>> +# One entry per manual page. List of tuples
>> +# (source start file, name, description, authors, manual section).
>> +man_pages = [
>> +    (master_doc, 'libcamera', 'LibCamera Documentation',
>> +     [author], 1)
>> +]
>> +
>> +
>> +# -- Options for Texinfo output ----------------------------------------------
>> +
>> +# Grouping the document tree into Texinfo files. List of tuples
>> +# (source start file, target name, title, author,
>> +#  dir menu entry, description, category)
>> +texinfo_documents = [
>> +    (master_doc, 'LibCamera', 'LibCamera Documentation',
>> +     author, 'LibCamera', 'One line description of project.',
>> +     'Miscellaneous'),
>> +]
>> +
>> +
>> +# -- Options for Epub output -------------------------------------------------
>> +
>> +# Bibliographic Dublin Core info.
>> +epub_title = project
>> +
>> +# The unique identifier of the text. This can be a ISBN number
>> +# or the project homepage.
>> +#
>> +# epub_identifier = ''
>> +
>> +# A unique identification for the text.
>> +#
>> +# epub_uid = ''
>> +
>> +# A list of files that should not be packed into the epub file.
>> +epub_exclude_files = ['search.html']
>> \ No newline at end of file
>> diff --git a/Documentation/hacking.rst b/Documentation/hacking.rst
>> new file mode 100644
>> index 000000000000..2dbee7f2b88d
>> --- /dev/null
>> +++ b/Documentation/hacking.rst
>> @@ -0,0 +1,42 @@
>> +Hacking and Development
>> +=======================
>> +
>> +libcamera is developed as a free software project and welcomes contributors.
>> +Whether you would like to help with coding, documentation, testing, proposing
>> +new features, or just discussing the project with the community, you can join
>> +our official public communication channels, or simply check out the code.
>> +Mailing List
> 
> This seems odd, should not the 'Mailing List' also have a line of - to 
> make it a subsection?


Ah yes, thank you I had missed that. This was just a copy paste from the
website.

> 
> With these issues addressed feel free to add
> 
> Reviewed-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>

I'll take this and commit to master :)


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

It might help if I add a link to the libcamera-devel list page here too :)


>> +
>> +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..962192ec8ee8
>> --- /dev/null
>> +++ b/Documentation/index.rst
>> @@ -0,0 +1,30 @@
>> +LibCamera abstraction library
>> +=============================
>> +
>> +Cameras are complex devices that need heavy hardware image processing
>> +operations. Control of the processing is based on advanced algorithms that must
>> +run on a programmable processor. This has traditionally been implemented in a
>> +dedicated MCU in the camera, but in embedded devices algorithms have been moved
>> +to the main CPU to save cost. Blurring the boundary between camera devices and
>> +Linux often left the user with no other option than a vendor-specific
>> +closed-source solution.
>> +
>> +To address this problem the Linux media community has very recently started
>> +collaboration with the industry to develop a camera stack that will be
>> +open-source-friendly while still protecting vendor core IP. libcamera was born
>> +out of that collaboration and will offer modern camera support to Linux-based
>> +systems, including traditional Linux distributions, ChromeOS and Android.
>> +
>> +
>> +.. toctree::
>> +   :maxdepth: 2
>> +   :caption: Contents:
>> +
>> +   hacking
>> +
>> +
>> +Indices and tables
>> +==================
>> +
>> +* :ref:`genindex`
>> +* :ref:`search`
>> diff --git a/Documentation/meson.build b/Documentation/meson.build
>> new file mode 100644
>> index 000000000000..5ab04479d3fb
>> --- /dev/null
>> +++ b/Documentation/meson.build
>> @@ -0,0 +1,20 @@
>> +sphinx = find_program('sphinx-build-3', required: false)
>> +if not sphinx.found()
>> +    sphinx = find_program('sphinx-build', required: false)
>> +endif
>> +
>> +if sphinx.found()
>> +    docs_sources = [
>> +	'hacking.rst',
>> +	'index.rst',
>> +    ]
>> +
>> +    custom_target('en user documentation',
>> +		  command: [sphinx, '-W', '-b', 'html', meson.current_source_dir(), '@OUTPUT@'],
>> +		  input: docs_sources,
>> +		  output: 'en',
>> +		  build_by_default: true)
>> +
>> +    install_subdir(meson.current_build_dir() + '/en',
>> +		  install_dir: 'share/doc/libcamera- at 0@/user'.format(api_version))
>> +endif
>> diff --git a/meson.build b/meson.build
>> index 4b3d528c8932..434aa557b8a1 100644
>> --- a/meson.build
>> +++ b/meson.build
>> @@ -2,8 +2,14 @@ project('libcamera - supporting complex camera pipelines', 'c', 'cpp',
>>    version : '0.1',
>>    license : 'LGPL 2.1+')
>>  
>> +# TODO: Extract this from project.version.
>> +#	Ideally the version at Documentation/conf.py should be
>> +#	generated from this too.
>> +api_version = '0.1'
>> +
>>  inc = include_directories('include')
>>  
>> +subdir('Documentation')
>>  subdir('lib')
>>  subdir('test')
>>  subdir('utils')
>> -- 
>> 2.17.1
>>
>> _______________________________________________
>> libcamera-devel mailing list
>> libcamera-devel at lists.libcamera.org
>> https://lists.libcamera.org/listinfo/libcamera-devel
> 

-- 
Regards
--
Kieran