[PATCH 0/2] custom doc styling

[PATCH 0/2] custom doc styling

[Thomas Monjalon]

The file custom.css allows to change the theme from "Read the Docs".
The first patch makes it available without "ninja install".
The second patch allows the NIC overview tables to be "fullscreen".

Thomas Monjalon (2):
  doc: copy custom CSS on guides build
  doc: give full width to NIC overview page

 buildtools/call-sphinx-build.py | 9 +++++++++
 doc/guides/custom.css           | 8 ++++++++
 doc/guides/meson.build          | 2 --
 doc/guides/nics/overview.rst    | 2 ++
 4 files changed, 19 insertions(+), 2 deletions(-)

-- 
2.45.0

[PATCH 1/2] doc: copy custom CSS on guides build

[Thomas Monjalon]

The custom CSS file for Sphinx guides was copied during install,
but not during build time.
Before switching to Meson, the Makefile was copying this file
in the build steps, so the doc was complete and viewable
from the build directory.

It is especially useful to get full documentation in the build directory
when building only documentation with "ninja -C build doc".
The command "ninja install" was required to get the CSS file installed,
but it requires to build the libraries as well.

The CSS file is now copied as part of the Sphinx build script,
and it will be installed as part of the whole html directory.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
 buildtools/call-sphinx-build.py | 9 +++++++++
 doc/guides/meson.build          | 2 --
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py
index da19e950c9..99e396bdd7 100755
--- a/buildtools/call-sphinx-build.py
+++ b/buildtools/call-sphinx-build.py
@@ -3,6 +3,8 @@
 # Copyright(c) 2019 Intel Corporation
 #
 
+import filecmp
+import shutil
 import sys
 import os
 from os.path import join
@@ -30,4 +32,11 @@
 with open(join(dst, '.html.d'), 'w') as d:
     d.write('html: ' + ' '.join(srcfiles) + '\n')
 
+# copy custom CSS file
+css = 'custom.css'
+src_css = join(src, css)
+dst_css = join(dst, 'html', '_static', 'css', css)
+if not os.path.exists(dst_css) or not filecmp.cmp(src_css, dst_css):
+    shutil.copyfile(src_css, dst_css)
+
 sys.exit(process.returncode)
diff --git a/doc/guides/meson.build b/doc/guides/meson.build
index 51f81da2e3..f8bbfba9f5 100644
--- a/doc/guides/meson.build
+++ b/doc/guides/meson.build
@@ -24,7 +24,5 @@ html_guides = custom_target('html_guides',
         install: get_option('enable_docs'),
         install_dir: htmldir)
 
-install_data(files('custom.css'), install_dir: join_paths(htmldir,'_static', 'css'))
-
 doc_targets += html_guides
 doc_target_names += 'HTML_Guides'
-- 
2.45.0

[PATCH 2/2] doc: give full width to NIC overview page

[Thomas Monjalon]

The wide tables in the NIC overview exceed the normal page width
because of the large number of drivers.

A CSS trick is added to allow displaying this page in the full width
of the browser window.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
 doc/guides/custom.css        | 8 ++++++++
 doc/guides/nics/overview.rst | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/doc/guides/custom.css b/doc/guides/custom.css
index 221024655c..df1a52f1d4 100644
--- a/doc/guides/custom.css
+++ b/doc/guides/custom.css
@@ -4,6 +4,14 @@
 
 /* Override readthedocs theme */
 
+/* Set full width on a page.
+ * Usage: insert the following line in the doc.
+ *        .. rst-class:: widepage
+ */
+.wy-nav-content:has(.widepage) {
+    max-width: none !important;
+}
+
 /* Spacing before a list item must be bigger than spacing inside the item.
  * Complex list items start with a p.first element. */
 .section li > .first {
diff --git a/doc/guides/nics/overview.rst b/doc/guides/nics/overview.rst
index 67575c699c..4553076481 100644
--- a/doc/guides/nics/overview.rst
+++ b/doc/guides/nics/overview.rst
@@ -24,6 +24,8 @@ Most of these differences are summarized below.
 
 More details about features can be found in :doc:`features`.
 
+.. rst-class:: widepage
+
 .. _table_net_pmd_features:
 
 .. include:: overview_table.txt
-- 
2.45.0

[PATCH v2 0/2] custom doc styling

[Thomas Monjalon]

The file custom.css allows to change the theme from "Read the Docs".
The first patch makes it available without "ninja install".
The second patch allows the NIC overview tables to be "fullscreen".

Thomas Monjalon (2):
  doc: copy custom CSS on guides build
  doc: give full width to NIC overview page

 buildtools/call-sphinx-build.py | 10 ++++++++++
 doc/guides/custom.css           |  8 ++++++++
 doc/guides/meson.build          |  2 --
 doc/guides/nics/overview.rst    |  2 ++
 4 files changed, 20 insertions(+), 2 deletions(-)

-- 
2.45.0

[PATCH v2 1/2] doc: copy custom CSS on guides build

[Thomas Monjalon]

The custom CSS file for Sphinx guides was copied during install,
but not during build time.
Before switching to Meson, the Makefile was copying this file
in the build steps, so the doc was complete and viewable
from the build directory.

It is especially useful to get full documentation in the build directory
when building only documentation with "ninja -C build doc".
The command "ninja install" was required to get the CSS file installed,
but it requires to build the libraries as well.

The CSS file is now copied as part of the Sphinx build script,
and it will be installed as part of the whole html directory.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
v2: create destination directory in case RtD theme is unavailable
---
 buildtools/call-sphinx-build.py | 10 ++++++++++
 doc/guides/meson.build          |  2 --
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py
index da19e950c9..623e7363ee 100755
--- a/buildtools/call-sphinx-build.py
+++ b/buildtools/call-sphinx-build.py
@@ -3,6 +3,8 @@
 # Copyright(c) 2019 Intel Corporation
 #
 
+import filecmp
+import shutil
 import sys
 import os
 from os.path import join
@@ -30,4 +32,12 @@
 with open(join(dst, '.html.d'), 'w') as d:
     d.write('html: ' + ' '.join(srcfiles) + '\n')
 
+# copy custom CSS file
+css = 'custom.css'
+src_css = join(src, css)
+dst_css = join(dst, 'html', '_static', 'css', css)
+if not os.path.exists(dst_css) or not filecmp.cmp(src_css, dst_css):
+    os.makedirs(os.path.dirname(dst_css), exist_ok=True)
+    shutil.copyfile(src_css, dst_css)
+
 sys.exit(process.returncode)
diff --git a/doc/guides/meson.build b/doc/guides/meson.build
index 51f81da2e3..f8bbfba9f5 100644
--- a/doc/guides/meson.build
+++ b/doc/guides/meson.build
@@ -24,7 +24,5 @@ html_guides = custom_target('html_guides',
         install: get_option('enable_docs'),
         install_dir: htmldir)
 
-install_data(files('custom.css'), install_dir: join_paths(htmldir,'_static', 'css'))
-
 doc_targets += html_guides
 doc_target_names += 'HTML_Guides'
-- 
2.45.0

Re: [PATCH v2 1/2] doc: copy custom CSS on guides build

[Ferruh Yigit]

On 7/31/2024 9:31 AM, Thomas Monjalon wrote:
> The custom CSS file for Sphinx guides was copied during install,
> but not during build time.
> Before switching to Meson, the Makefile was copying this file
> in the build steps, so the doc was complete and viewable
> from the build directory.
> 
> It is especially useful to get full documentation in the build directory
> when building only documentation with "ninja -C build doc".
> The command "ninja install" was required to get the CSS file installed,
> but it requires to build the libraries as well.
> 
> The CSS file is now copied as part of the Sphinx build script,
> and it will be installed as part of the whole html directory.
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
>

Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>
Tested-by: Ferruh Yigit <ferruh.yigit@amd.com>

[PATCH v2 2/2] doc: give full width to NIC overview page

[Thomas Monjalon]

The wide tables in the NIC overview exceed the normal page width
because of the large number of drivers.

A CSS trick is added to allow displaying this page in the full width
of the browser window.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
v2: no change
---
 doc/guides/custom.css        | 8 ++++++++
 doc/guides/nics/overview.rst | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/doc/guides/custom.css b/doc/guides/custom.css
index 221024655c..df1a52f1d4 100644
--- a/doc/guides/custom.css
+++ b/doc/guides/custom.css
@@ -4,6 +4,14 @@
 
 /* Override readthedocs theme */
 
+/* Set full width on a page.
+ * Usage: insert the following line in the doc.
+ *        .. rst-class:: widepage
+ */
+.wy-nav-content:has(.widepage) {
+    max-width: none !important;
+}
+
 /* Spacing before a list item must be bigger than spacing inside the item.
  * Complex list items start with a p.first element. */
 .section li > .first {
diff --git a/doc/guides/nics/overview.rst b/doc/guides/nics/overview.rst
index 67575c699c..4553076481 100644
--- a/doc/guides/nics/overview.rst
+++ b/doc/guides/nics/overview.rst
@@ -24,6 +24,8 @@ Most of these differences are summarized below.
 
 More details about features can be found in :doc:`features`.
 
+.. rst-class:: widepage
+
 .. _table_net_pmd_features:
 
 .. include:: overview_table.txt
-- 
2.45.0

Re: [PATCH v2 2/2] doc: give full width to NIC overview page

[Ferruh Yigit]

On 7/31/2024 9:31 AM, Thomas Monjalon wrote:
> The wide tables in the NIC overview exceed the normal page width
> because of the large number of drivers.
> 
> A CSS trick is added to allow displaying this page in the full width
> of the browser window.
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
>

This makes the feature table wider, so all table can fit, and scroll bar
below the table is gone, this is good.

But also it makes all paragraphs and 'Note' boxes in that page fill all
the screen, and with a wide screen this becomes a long box through end
of the screen and personally I think doesn't look nice.

Instead of making it full screen, is there are way to make it fixed
size, but larger than previous so that table still can expand fully?

Re: [PATCH v2 2/2] doc: give full width to NIC overview page

[Thomas Monjalon]

31/07/2024 13:29, Ferruh Yigit:
> On 7/31/2024 9:31 AM, Thomas Monjalon wrote:
> > The wide tables in the NIC overview exceed the normal page width
> > because of the large number of drivers.
> > 
> > A CSS trick is added to allow displaying this page in the full width
> > of the browser window.
> > 
> > Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> >
> 
> This makes the feature table wider, so all table can fit, and scroll bar
> below the table is gone, this is good.
> 
> But also it makes all paragraphs and 'Note' boxes in that page fill all
> the screen, and with a wide screen this becomes a long box through end
> of the screen and personally I think doesn't look nice.
> 
> Instead of making it full screen, is there are way to make it fixed
> size, but larger than previous so that table still can expand fully?

We may try to restrict non-table containers, but then it will be less generic.
I mean this solution could apply to any large page today.

We may try to force the width of <p> and <ul>.

Re: [PATCH v2 2/2] doc: give full width to NIC overview page

[Thomas Monjalon]

31/07/2024 14:43, Thomas Monjalon:
> 31/07/2024 13:29, Ferruh Yigit:
> > On 7/31/2024 9:31 AM, Thomas Monjalon wrote:
> > > The wide tables in the NIC overview exceed the normal page width
> > > because of the large number of drivers.
> > > 
> > > A CSS trick is added to allow displaying this page in the full width
> > > of the browser window.
> > > 
> > > Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> > >
> > 
> > This makes the feature table wider, so all table can fit, and scroll bar
> > below the table is gone, this is good.
> > 
> > But also it makes all paragraphs and 'Note' boxes in that page fill all
> > the screen, and with a wide screen this becomes a long box through end
> > of the screen and personally I think doesn't look nice.
> > 
> > Instead of making it full screen, is there are way to make it fixed
> > size, but larger than previous so that table still can expand fully?
> 
> We may try to restrict non-table containers, but then it will be less generic.
> I mean this solution could apply to any large page today.
> 
> We may try to force the width of <p> and <ul>.

I've found another trick to let only tables overflow.
I'll send a v3 and will apply quickly.

[PATCH v3 0/2] custom doc styling

[Thomas Monjalon]

The file custom.css allows to change the theme from "Read the Docs".
The first patch makes it available without "ninja install".
The second patch allows the NIC overview tables to be "fullscreen".

Thomas Monjalon (2):
  doc: copy custom CSS on guides build
  doc: give full width to NIC overview page

 buildtools/call-sphinx-build.py | 10 ++++++++++
 doc/guides/custom.css           | 13 +++++++++++++
 doc/guides/meson.build          |  2 --
 doc/guides/nics/overview.rst    |  2 ++
 4 files changed, 25 insertions(+), 2 deletions(-)

-- 
2.45.0

[PATCH v3 1/2] doc: copy custom CSS on guides build

[Thomas Monjalon]

The custom CSS file for Sphinx guides was copied during install,
but not during build time.
Before switching to Meson, the Makefile was copying this file
in the build steps, so the doc was complete and viewable
from the build directory.

It is especially useful to get full documentation in the build directory
when building only documentation with "ninja -C build doc".
The command "ninja install" was required to get the CSS file installed,
but it requires to build the libraries as well.

The CSS file is now copied as part of the Sphinx build script,
and it will be installed as part of the whole html directory.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>
---
v2: create destination directory in case RtD theme is unavailable
v3: no change
---
 buildtools/call-sphinx-build.py | 10 ++++++++++
 doc/guides/meson.build          |  2 --
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py
index da19e950c9..623e7363ee 100755
--- a/buildtools/call-sphinx-build.py
+++ b/buildtools/call-sphinx-build.py
@@ -3,6 +3,8 @@
 # Copyright(c) 2019 Intel Corporation
 #
 
+import filecmp
+import shutil
 import sys
 import os
 from os.path import join
@@ -30,4 +32,12 @@
 with open(join(dst, '.html.d'), 'w') as d:
     d.write('html: ' + ' '.join(srcfiles) + '\n')
 
+# copy custom CSS file
+css = 'custom.css'
+src_css = join(src, css)
+dst_css = join(dst, 'html', '_static', 'css', css)
+if not os.path.exists(dst_css) or not filecmp.cmp(src_css, dst_css):
+    os.makedirs(os.path.dirname(dst_css), exist_ok=True)
+    shutil.copyfile(src_css, dst_css)
+
 sys.exit(process.returncode)
diff --git a/doc/guides/meson.build b/doc/guides/meson.build
index 51f81da2e3..f8bbfba9f5 100644
--- a/doc/guides/meson.build
+++ b/doc/guides/meson.build
@@ -24,7 +24,5 @@ html_guides = custom_target('html_guides',
         install: get_option('enable_docs'),
         install_dir: htmldir)
 
-install_data(files('custom.css'), install_dir: join_paths(htmldir,'_static', 'css'))
-
 doc_targets += html_guides
 doc_target_names += 'HTML_Guides'
-- 
2.45.0

[PATCH v3 2/2] doc: give full width to NIC overview page

[Thomas Monjalon]

The wide tables in the NIC overview exceed the normal page width
because of the large number of drivers.

A CSS trick is added to allow displaying the tables in the full width
of the browser window.

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
v2: no change
v3: let only tables to overflow on wide screen
---
 doc/guides/custom.css        | 13 +++++++++++++
 doc/guides/nics/overview.rst |  2 ++
 2 files changed, 15 insertions(+)

diff --git a/doc/guides/custom.css b/doc/guides/custom.css
index 221024655c..a8ee6bed2c 100644
--- a/doc/guides/custom.css
+++ b/doc/guides/custom.css
@@ -4,6 +4,19 @@
 
 /* Override readthedocs theme */
 
+/* Set full width for all responsive tables of a page.
+ * Usage: insert the following line in the doc.
+ *        .. rst-class:: widepage
+ */
+@media screen and (min-width: 1100px) {
+    .wy-nav-content-wrap:has(.widepage) {
+        background: white !important;
+    }
+    .wy-nav-content:has(.widepage) .wy-table-responsive {
+        overflow: visible !important;
+    }
+}
+
 /* Spacing before a list item must be bigger than spacing inside the item.
  * Complex list items start with a p.first element. */
 .section li > .first {
diff --git a/doc/guides/nics/overview.rst b/doc/guides/nics/overview.rst
index 67575c699c..4553076481 100644
--- a/doc/guides/nics/overview.rst
+++ b/doc/guides/nics/overview.rst
@@ -24,6 +24,8 @@ Most of these differences are summarized below.
 
 More details about features can be found in :doc:`features`.
 
+.. rst-class:: widepage
+
 .. _table_net_pmd_features:
 
 .. include:: overview_table.txt
-- 
2.45.0

Re: [PATCH v3 2/2] doc: give full width to NIC overview page

[Ferruh Yigit]

On 7/31/2024 4:57 PM, Thomas Monjalon wrote:
> The wide tables in the NIC overview exceed the normal page width
> because of the large number of drivers.
> 
> A CSS trick is added to allow displaying the tables in the full width
> of the browser window.
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> ---
> v2: no change
> v3: let only tables to overflow on wide screen
>

It is better, thanks. Now page boundaries are kept but table extended to
fit all columns.

You are improving front-end skills :)

Only color of the overview page is not white as it is in other pages,
but slight gray, is this intentional?

Re: [PATCH v3 2/2] doc: give full width to NIC overview page

[Thomas Monjalon]

31/07/2024 18:17, Ferruh Yigit:
> On 7/31/2024 4:57 PM, Thomas Monjalon wrote:
> > The wide tables in the NIC overview exceed the normal page width
> > because of the large number of drivers.
> > 
> > A CSS trick is added to allow displaying the tables in the full width
> > of the browser window.
> > 
> > Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> > ---
> > v2: no change
> > v3: let only tables to overflow on wide screen
> >
> 
> It is better, thanks. Now page boundaries are kept but table extended to
> fit all columns.
> 
> You are improving front-end skills :)

Thanks, that's a fun skill to work on :)

> Only color of the overview page is not white as it is in other pages,
> but slight gray, is this intentional?

It seems all pages are not really white, but #fcfcfc.
I'll apply the same color for the whole background of the tables.

Re: [PATCH v3 0/2] custom doc styling

[Thomas Monjalon]

31/07/2024 17:57, Thomas Monjalon:
> The file custom.css allows to change the theme from "Read the Docs".
> The first patch makes it available without "ninja install".
> The second patch allows the NIC overview tables to be "fullscreen".
> 
> Thomas Monjalon (2):
>   doc: copy custom CSS on guides build
>   doc: give full width to NIC overview page

Applied with background color fixed.

Re: [PATCH v3 0/2] custom doc styling

[Ferruh Yigit]

On 7/31/2024 5:22 PM, Thomas Monjalon wrote:
> 31/07/2024 17:57, Thomas Monjalon:
>> The file custom.css allows to change the theme from "Read the Docs".
>> The first patch makes it available without "ninja install".
>> The second patch allows the NIC overview tables to be "fullscreen".
>>
>> Thomas Monjalon (2):
>>   doc: copy custom CSS on guides build
>>   doc: give full width to NIC overview page
> 
> Applied with background color fixed.
> 

You already applied, but let me give my explicit ack for record:

Acked-by: Ferruh Yigit <ferruh.yigit@amd.com>