[libcamera-devel,6/8] Documentation: Hide the Getting Started information

2204 diff mbox series

The Getting Started information makes little sense on the generated
documentation, as a developer with documentation compiled from a local
libcamera source tree has already got started. We however want to keep
the information in the top-level README.rst as it is useful there.

In order to hide the Getting Started information from the front page
while keeping it in README.rst, add comments to delimitate sections of
README.rst, and include only a subset of the file in the front page.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
 Documentation/index.rst | 2 ++
 README.rst              | 9 ++++++++-
 2 files changed, 10 insertions(+), 1 deletion(-)

Hi Laurent,

On 21/10/2019 11:24, Laurent Pinchart wrote:
> The Getting Started information makes little sense on the generated
> documentation, as a developer with documentation compiled from a local
> libcamera source tree has already got started. We however want to keep
> the information in the top-level README.rst as it is useful there.

A developer who has built the documentation can indeed be assumed to
have gotten started to some degree, but they might still want to find
references to the required packages for optional components.

They could of course look in README.rst too, but I'd also envisage that
'getting started' would have more development hints in the future
perhaps too.

So I'm sort of against the removal of this section.

I'd also prefer the site, and local builds to be as close as possible,
and this makes (what I perceive to be) an unnecessary diff between the
two versions.

Still, The patch does correctly do as you describe, so on that basis:

Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>


And I'll leave it up to you to decide if you still want to include it or
not.

--
Kieran




> In order to hide the Getting Started information from the front page
> while keeping it in README.rst, add comments to delimitate sections of
> README.rst, and include only a subset of the file in the front page.
> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
>  Documentation/index.rst | 2 ++
>  README.rst              | 9 ++++++++-
>  2 files changed, 10 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 28267cec36b7..2c84a5401506 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -1,5 +1,7 @@
>  .. Front page matter is defined in the project README file.
>  .. include:: ../README.rst
> +   :start-after: .. section-begin-libcamera
> +   :end-before: .. section-end-libcamera
>  
>  .. toctree::
>     :maxdepth: 1
> diff --git a/README.rst b/README.rst
> index 2ccf7cbec40a..220ebdb17a42 100644
> --- a/README.rst
> +++ b/README.rst
> @@ -1,3 +1,5 @@
> +.. section-begin-libcamera
> +
>  ===========
>   libcamera
>  ===========
> @@ -18,6 +20,9 @@ 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.
>  
> +.. section-end-libcamera
> +.. section-begin-getting-started
> +
>  Getting Started
>  ---------------
>  
> @@ -31,7 +36,7 @@ To build and install:
>    ninja install
>  
>  Dependencies
> -------------
> +~~~~~~~~~~~~
>  
>  The following Debian/Ubuntu packages are required for building libcamera.
>  Other distributions may have differing package names:
> @@ -50,3 +55,5 @@ for qcam: [optional]
>  
>  for documentation: [optional]
>  	python3-sphinx doxygen
> +
> +.. section-end-getting-started
>