[v2,7/7] Documentation: Rework index.rst
diff mbox series

Message ID 20240815082944.170109-8-dan.scally@ideasonboard.com
State Superseded
Headers show
Series
  • Documentation improvements
Related show

Commit Message

Daniel Scally Aug. 15, 2024, 8:29 a.m. UTC
index.rst is the page that becomes index.html, but currently just has
some blurb. Although this page will only be seen if viewing the docs
as built from the libcamera tree it'd be better if it were more of an
introductory page. Include the content of docs.rst to improve it. As
we're no longer including the content from README.rst the labels that
enabled that can be dropped.

With this change whether viewing the documentation as built in the
libcamera tree or on the Docs page of the website, the landing content
will be the same.

The CSS for the documentation's theme currently hides the toctree from
the generated body in html, as it's already displayed on every page via
the theme's CSS. This change reorders the page such that the CSS that
hides the toctree no longer works - update the CSS to retain the
current behaviour.

Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
---
Changes since v1:

	- Removed superfluous comments
	- Expanded commit message

 Documentation/index.rst                  | 11 ++++++-----
 Documentation/theme/static/css/theme.css |  2 +-
 README.rst                               |  3 ---
 3 files changed, 7 insertions(+), 9 deletions(-)

Comments

Laurent Pinchart Aug. 18, 2024, 11:07 p.m. UTC | #1
Hi Dan,

Thank you for the patch.

On Thu, Aug 15, 2024 at 09:29:44AM +0100, Daniel Scally wrote:
> index.rst is the page that becomes index.html, but currently just has
> some blurb. Although this page will only be seen if viewing the docs
> as built from the libcamera tree it'd be better if it were more of an
> introductory page. Include the content of docs.rst to improve it. As
> we're no longer including the content from README.rst the labels that
> enabled that can be dropped.
> 
> With this change whether viewing the documentation as built in the
> libcamera tree or on the Docs page of the website, the landing content
> will be the same.

That's a nice improvement, thanks.

> 
> The CSS for the documentation's theme currently hides the toctree from
> the generated body in html, as it's already displayed on every page via
> the theme's CSS. This change reorders the page such that the CSS that
> hides the toctree no longer works - update the CSS to retain the
> current behaviour.
> 
> Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

> ---
> Changes since v1:
> 
> 	- Removed superfluous comments
> 	- Expanded commit message
> 
>  Documentation/index.rst                  | 11 ++++++-----
>  Documentation/theme/static/css/theme.css |  2 +-
>  README.rst                               |  3 ---
>  3 files changed, 7 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 6d7d2ca3..a27061aa 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -1,16 +1,12 @@
>  .. SPDX-License-Identifier: CC-BY-SA-4.0
>  
> -.. Front page matter is defined in the project README file.
> -.. include:: ../README.rst
> -   :start-after: .. section-begin-libcamera
> -   :end-before: .. section-end-libcamera
> +.. include:: docs.rst
>  
>  .. toctree::
>     :maxdepth: 1
>     :caption: Contents:
>  
>     Home <self>
> -   Docs <docs>
>     Contribute <contributing>
>     Getting Started <getting-started>
>  
> @@ -26,3 +22,8 @@
>     Sensor driver requirements <sensor_driver_requirements>
>     SoftwareISP Benchmarking <software-isp-benchmarking>
>     Tracing guide <guides/tracing>
> +
> +.. toctree::
> +   :hidden:
> +
> +   docs
> \ No newline at end of file
> diff --git a/Documentation/theme/static/css/theme.css b/Documentation/theme/static/css/theme.css
> index 2b1ed095..a6d43195 100644
> --- a/Documentation/theme/static/css/theme.css
> +++ b/Documentation/theme/static/css/theme.css
> @@ -283,7 +283,7 @@ div#signature {
>  	font-size: 12px;
>  }
>  
> -#libcamera div.toctree-wrapper {
> +#licensing div.toctree-wrapper {
>  	height: 0px;
>  	margin: 0px;
>  	padding: 0px;
> diff --git a/README.rst b/README.rst
> index 92f16502..4068c6cc 100644
> --- a/README.rst
> +++ b/README.rst
> @@ -1,7 +1,5 @@
>  .. SPDX-License-Identifier: CC-BY-SA-4.0
>  
> -.. section-begin-libcamera
> -
>  ===========
>   libcamera
>  ===========
> @@ -22,7 +20,6 @@ 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

Patch
diff mbox series

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 6d7d2ca3..a27061aa 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -1,16 +1,12 @@ 
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
-.. Front page matter is defined in the project README file.
-.. include:: ../README.rst
-   :start-after: .. section-begin-libcamera
-   :end-before: .. section-end-libcamera
+.. include:: docs.rst
 
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
    Home <self>
-   Docs <docs>
    Contribute <contributing>
    Getting Started <getting-started>
 
@@ -26,3 +22,8 @@ 
    Sensor driver requirements <sensor_driver_requirements>
    SoftwareISP Benchmarking <software-isp-benchmarking>
    Tracing guide <guides/tracing>
+
+.. toctree::
+   :hidden:
+
+   docs
\ No newline at end of file
diff --git a/Documentation/theme/static/css/theme.css b/Documentation/theme/static/css/theme.css
index 2b1ed095..a6d43195 100644
--- a/Documentation/theme/static/css/theme.css
+++ b/Documentation/theme/static/css/theme.css
@@ -283,7 +283,7 @@  div#signature {
 	font-size: 12px;
 }
 
-#libcamera div.toctree-wrapper {
+#licensing div.toctree-wrapper {
 	height: 0px;
 	margin: 0px;
 	padding: 0px;
diff --git a/README.rst b/README.rst
index 92f16502..4068c6cc 100644
--- a/README.rst
+++ b/README.rst
@@ -1,7 +1,5 @@ 
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
-.. section-begin-libcamera
-
 ===========
  libcamera
 ===========
@@ -22,7 +20,6 @@  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