[libcamera-devel] [PATCH 2/3] readme: Move index page content to README

[Laurent Pinchart]

Hi Kieran,

On Wed, Aug 14, 2019 at 12:46:15PM +0100, Kieran Bingham wrote:
> On 14/08/2019 12:29, Laurent Pinchart wrote:
> > On Wed, Aug 14, 2019 at 10:58:16AM +0100, Kieran Bingham wrote:
> >> Move the introduction content from the index.rst to the README.rst so
> >> that it can also be found quickly from the top level.
> >>
> >> Include the README.rst directly into the index.rst to continue serving
> >> it as the front page material.
> >>
> >> Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
> >> ---
> >>  Documentation/index.rst   | 19 ++-----------------
> >>  Documentation/meson.build |  1 +
> >>  README.rst                | 17 +++++++++++++++++
> >>  3 files changed, 20 insertions(+), 17 deletions(-)
> >>
> >> diff --git a/Documentation/index.rst b/Documentation/index.rst
> >> index e481f081f9a1..ec2222108e8a 100644
> >> --- a/Documentation/index.rst
> >> +++ b/Documentation/index.rst
> >> @@ -1,20 +1,5 @@
> >> -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.
> >> -
> >> +.. Front page matter is defined in the project README file.
> >> +.. include:: ../README.rst
> >>  
> >>  .. toctree::
> >>     :maxdepth: 2
> >> diff --git a/Documentation/meson.build b/Documentation/meson.build
> >> index b1720b05f5ee..a560d02abfa5 100644
> >> --- a/Documentation/meson.build
> >> +++ b/Documentation/meson.build
> >> @@ -41,6 +41,7 @@ endif
> >>  
> >>  if sphinx.found()
> >>      docs_sources = [
> >> +       '../README.rst',
> >>          'coding-style.rst',
> >>          'conf.py',
> >>          'contributing.rst',
> >> diff --git a/README.rst b/README.rst
> >> index 9a8261ac8502..0f64e076a9c0 100644
> >> --- a/README.rst
> >> +++ b/README.rst
> >> @@ -4,6 +4,23 @@
> >>  
> >>  **A complex camera support library for Linux, Android, and ChromeOS**
> > 
> > This makes the title smaller than the Getting Started and Dependencies
> > section below. Should we make it the same size ?
> 
> I wanted to mark this as a subtitle, but setting it so affects the
> toctree box, and produces:
> 
> * libcamera:
>  ** A complex camera support library for Linux, Android, and ChromeOS
>   *** Getting started.
> 
> and I don't think that subtitle should be in the hierarchy of the ToC.
> 
> The enlarged text also ended up wrapped, and didn't look as
> aesthetically pleasing ... so I felt this was the best rendering.
> 
> I see it more of the tagline or brief than a title so I'm not too
> worried about it being smaller than the section headers.
> 
> Would you prefer it was promoted to a subtitle?

I'll let you pick the option that you think is best.

> > Apart from that,
> > 
> > Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > 
> >> +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.
> >> +
> >> +Getting Started
> >> +---------------
> >> +
> >>  To build and install:
> >>  
> >>  ::

-- 
Regards,

Laurent Pinchart