[libcamera-devel] [PATCH] Documentation: camera-sensor-model: Support Sphinx < 2.0

[Jacopo Mondi]

Hi Laurent

On Tue, Jan 09, 2024 at 05:10:28PM +0200, Laurent Pinchart wrote:
> On Tue, Jan 09, 2024 at 04:06:00PM +0100, Jacopo Mondi wrote:
> > On Tue, Jan 09, 2024 at 04:30:02PM +0200, Laurent Pinchart wrote:
> > > The language argument to the code-block directive was mandatory in
> > > Sphinx before 2.0. Fix the few instances where no language is specified
> > > to support older versions of Sphinx.
> >
> > Thanks, good spot
> >
> > > Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > > ---
> > >  Documentation/camera-sensor-model.rst | 25 ++++++++++++-------------
> > >  1 file changed, 12 insertions(+), 13 deletions(-)
> > >
> > > diff --git a/Documentation/camera-sensor-model.rst b/Documentation/camera-sensor-model.rst
> > > index 58bf70e1dc5a..b66c880a5e00 100644
> > > --- a/Documentation/camera-sensor-model.rst
> > > +++ b/Documentation/camera-sensor-model.rst
> > > @@ -105,35 +105,34 @@ control:
> > >        will be downscaled in its vertical and horizontal sizes by the specified
> > >        factor.
> > >
> > > -      .. code-block::
> > > +      .. code-block:: c
> > >           :caption: Definition: The horizontal and vertical binning factors
> > >
> > >           horizontal_binning = xBin;
> > >           vertical_binning = yBin;
> > >
> > > -
> >
> > If I'm not mistaken, other code-block sections in this file were followed by 2
> > empty lines. You are here removing one in this instance, but the other
> > ones are not changed. Should we take the occasion to align all of them
> > to use a single empty line ?
>
> I'm fine either way. I think Kieran would like to integrate this
> quickly, so the whitespace cleanups could be done on top, or he can drop
> the extra lines locally.
>
> Kieran, please double-check the compiled documentation for formatting
> issues, even if it compiles fine with blank lines removed.
>

I see no visual differences in the two version and I've not found any
requirement about multiple empty lines after a code-block in the
Sphinx documentation

> > It's a minor, the rest looks good!
> >
> > Reviewed-by: Jacopo Mondi <jacopo.mondi at ideasonboard.com>
> >
> > >     - skipping
> > >        Skipping reduces the image resolution by skipping the read-out of a number
> > >        of adjacent pixels. The skipping factor is specified by the 'increment'
> > >        number (number of pixels to 'skip') in the vertical and horizontal
> > >        directions and for even and odd rows and columns.
> > >
> > > -      .. code-block::
> > > +      .. code-block:: c
> > >           :caption: Definition: The horizontal and vertical skipping factors
> > >
> > > -         horizontal_skipping = (xOddInc + xEvenInc) / 2
> > > -         vertical_skipping = (yOddInc + yEvenInc) / 2
> > > +         horizontal_skipping = (xOddInc + xEvenInc) / 2;
> > > +         vertical_skipping = (yOddInc + yEvenInc) / 2;
> > >
> > >     Different sensors perform the binning and skipping stages in different
> > >     orders. For the sake of computing the final output image size the order of
> > >     execution is not relevant. The overall down-scaling factor is obtained by
> > >     combining the binning and skipping factors.
> > >
> > > -   .. code-block::
> > > +   .. code-block:: c
> > >        :caption: Definition: The total scaling factor (binning + sub-sampling)
> > >
> > > -      total_horizontal_downscale = horizontal_binning + horizontal_skipping
> > > -      total_vertical_downscale = vertical_binning + vertical_skipping
> > > +      total_horizontal_downscale = horizontal_binning + horizontal_skipping;
> > > +      total_vertical_downscale = vertical_binning + vertical_skipping;
> > >
> > >
> > >  4. The output size is used to specify any additional cropping on the sub-sampled
> > > @@ -159,16 +158,16 @@ configurations:
> > >     the *pixel rate* of the data sent on the MIPI CSI-2 bus allows to compute the
> > >     image stream frame rate. The equation is the well known:
> > >
> > > -   .. code-block::
> > > +   .. code-block:: c
> > >
> > > -      frame_duration = total_frame_size / pixel_rate
> > > -      frame_rate = 1 / frame_duration
> > > +      frame_duration = total_frame_size / pixel_rate;
> > > +      frame_rate = 1 / frame_duration;
> > >
> > >
> > >     where the *pixel_rate* parameter is the result of the sensor's configuration
> > >     of the MIPI CSI-2 bus *(the following formula applies to MIPI CSI-2 when
> > >     used on MIPI D-PHY physical protocol layer only)*
> > >
> > > -   .. code-block::
> > > +   .. code-block:: c
> > >
> > > -      pixel_rate = CSI-2_link_freq * 2 * nr_of_lanes / bits_per_sample
> > > +      pixel_rate = csi_2_link_freq * 2 * nr_of_lanes / bits_per_sample;
>
> --
> Regards,
>
> Laurent Pinchart