[PATCH] dts: fix doxygen API link

[PATCH] dts: fix doxygen API link

[Paul Szczepanek]

Alias used to produce the link to the DTS API docs uses config data.
The required value in config data was being added in the wrong scope.
This moves the key addition to where the config data object is created.

Fixes: 7f9326423a04 ("dts: add API doc generation")

Signed-off-by: Paul Szczepanek <paul.szczepanek@arm.com>
Acked-by: Patrick Robb <probb@iol.unh.edu>
---
 doc/api/dts/meson.build | 2 --
 doc/api/meson.build     | 1 +
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/doc/api/dts/meson.build b/doc/api/dts/meson.build
index 5115df7095..5cb4a68dd4 100644
--- a/doc/api/dts/meson.build
+++ b/doc/api/dts/meson.build
@@ -11,8 +11,6 @@ if python_ver_satisfied != 0
     subdir_done()
 endif
 
-cdata.set('DTS_API_MAIN_PAGE', join_paths('..', 'dts', 'html', 'index.html'))
-
 extra_sphinx_args = ['-E', '-c', join_paths(doc_source_dir, 'guides')]
 if get_option('werror')
     extra_sphinx_args += '-W'
diff --git a/doc/api/meson.build b/doc/api/meson.build
index ae23e9825e..fdb04e0ec8 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -40,6 +40,7 @@ cdata.set('OUTPUT', join_paths(dpdk_build_root, 'doc', 'api'))
 cdata.set('TOPDIR', dpdk_source_root)
 cdata.set('STRIP_FROM_PATH', ' '.join([dpdk_source_root, join_paths(dpdk_build_root, 'doc', 'api')]))
 cdata.set('WARN_AS_ERROR', 'NO')
+cdata.set('DTS_API_MAIN_PAGE', join_paths(dpdk_build_root, 'doc', 'api', 'dts', 'html', 'index.html'))
 if get_option('werror')
     cdata.set('WARN_AS_ERROR', 'YES')
 endif
-- 
2.39.2

Re: [PATCH] dts: fix doxygen API link

[Luca Vizzarro]

Reviewed-by: Luca Vizzarro <luca.vizzarro@arm.com>

Re: [PATCH] dts: fix doxygen API link

[David Marchand]

On Wed, Oct 23, 2024 at 4:58 PM Paul Szczepanek <paul.szczepanek@arm.com> wrote:
>
> Alias used to produce the link to the DTS API docs uses config data.
> The required value in config data was being added in the wrong scope.
> This moves the key addition to where the config data object is created.
>
> Fixes: 7f9326423a04 ("dts: add API doc generation")
>
> Signed-off-by: Paul Szczepanek <paul.szczepanek@arm.com>
> Acked-by: Patrick Robb <probb@iol.unh.edu>

Good timing, I was about to send a report about this warning.

This makes the warning disappear (and the dts doc generates).
Tested-by: David Marchand <david.marchand@redhat.com>

Patrick, I'll merge it directly in main, is that ok for you?


-- 
David Marchand

Re: [PATCH] dts: fix doxygen API link

[Patrick Robb]

Yes that's fine thanks David!

Re: [PATCH] dts: fix doxygen API link

[David Marchand]

On Wed, Oct 23, 2024 at 4:58 PM Paul Szczepanek <paul.szczepanek@arm.com> wrote:
>
> Alias used to produce the link to the DTS API docs uses config data.
> The required value in config data was being added in the wrong scope.
> This moves the key addition to where the config data object is created.
>
> Fixes: 7f9326423a04 ("dts: add API doc generation")
>
> Signed-off-by: Paul Szczepanek <paul.szczepanek@arm.com>
> Acked-by: Patrick Robb <probb@iol.unh.edu>
> ---
>  doc/api/dts/meson.build | 2 --
>  doc/api/meson.build     | 1 +
>  2 files changed, 1 insertion(+), 2 deletions(-)
>
> diff --git a/doc/api/dts/meson.build b/doc/api/dts/meson.build
> index 5115df7095..5cb4a68dd4 100644
> --- a/doc/api/dts/meson.build
> +++ b/doc/api/dts/meson.build
> @@ -11,8 +11,6 @@ if python_ver_satisfied != 0
>      subdir_done()
>  endif
>
> -cdata.set('DTS_API_MAIN_PAGE', join_paths('..', 'dts', 'html', 'index.html'))
> -
>  extra_sphinx_args = ['-E', '-c', join_paths(doc_source_dir, 'guides')]
>  if get_option('werror')
>      extra_sphinx_args += '-W'
> diff --git a/doc/api/meson.build b/doc/api/meson.build
> index ae23e9825e..fdb04e0ec8 100644
> --- a/doc/api/meson.build
> +++ b/doc/api/meson.build
> @@ -40,6 +40,7 @@ cdata.set('OUTPUT', join_paths(dpdk_build_root, 'doc', 'api'))
>  cdata.set('TOPDIR', dpdk_source_root)
>  cdata.set('STRIP_FROM_PATH', ' '.join([dpdk_source_root, join_paths(dpdk_build_root, 'doc', 'api')]))
>  cdata.set('WARN_AS_ERROR', 'NO')
> +cdata.set('DTS_API_MAIN_PAGE', join_paths(dpdk_build_root, 'doc', 'api', 'dts', 'html', 'index.html'))
>  if get_option('werror')
>      cdata.set('WARN_AS_ERROR', 'YES')
>  endif

Looking again while applying, something is fishy in doc/api/meson.build:

if not doxygen.found()
  # process DTS API doc build even if DPDK API doc build can't be done
  cdata = configuration_data()
  subdir('dts')
  subdir_done()
endif

Should this cdata (unused afaics) object be removed too?


-- 
David Marchand

Re: [PATCH] dts: fix doxygen API link

[David Marchand]

On Wed, Oct 23, 2024 at 5:30 PM David Marchand
<david.marchand@redhat.com> wrote:
>
> On Wed, Oct 23, 2024 at 4:58 PM Paul Szczepanek <paul.szczepanek@arm.com> wrote:
> >
> > Alias used to produce the link to the DTS API docs uses config data.
> > The required value in config data was being added in the wrong scope.
> > This moves the key addition to where the config data object is created.
> >
> > Fixes: 7f9326423a04 ("dts: add API doc generation")
> >
> > Signed-off-by: Paul Szczepanek <paul.szczepanek@arm.com>
> > Acked-by: Patrick Robb <probb@iol.unh.edu>
> > ---
> >  doc/api/dts/meson.build | 2 --
> >  doc/api/meson.build     | 1 +
> >  2 files changed, 1 insertion(+), 2 deletions(-)
> >
> > diff --git a/doc/api/dts/meson.build b/doc/api/dts/meson.build
> > index 5115df7095..5cb4a68dd4 100644
> > --- a/doc/api/dts/meson.build
> > +++ b/doc/api/dts/meson.build
> > @@ -11,8 +11,6 @@ if python_ver_satisfied != 0
> >      subdir_done()
> >  endif
> >
> > -cdata.set('DTS_API_MAIN_PAGE', join_paths('..', 'dts', 'html', 'index.html'))
> > -
> >  extra_sphinx_args = ['-E', '-c', join_paths(doc_source_dir, 'guides')]
> >  if get_option('werror')
> >      extra_sphinx_args += '-W'
> > diff --git a/doc/api/meson.build b/doc/api/meson.build
> > index ae23e9825e..fdb04e0ec8 100644
> > --- a/doc/api/meson.build
> > +++ b/doc/api/meson.build
> > @@ -40,6 +40,7 @@ cdata.set('OUTPUT', join_paths(dpdk_build_root, 'doc', 'api'))
> >  cdata.set('TOPDIR', dpdk_source_root)
> >  cdata.set('STRIP_FROM_PATH', ' '.join([dpdk_source_root, join_paths(dpdk_build_root, 'doc', 'api')]))
> >  cdata.set('WARN_AS_ERROR', 'NO')
> > +cdata.set('DTS_API_MAIN_PAGE', join_paths(dpdk_build_root, 'doc', 'api', 'dts', 'html', 'index.html'))
> >  if get_option('werror')
> >      cdata.set('WARN_AS_ERROR', 'YES')
> >  endif
>
> Looking again while applying, something is fishy in doc/api/meson.build:
>
> if not doxygen.found()
>   # process DTS API doc build even if DPDK API doc build can't be done
>   cdata = configuration_data()
>   subdir('dts')
>   subdir_done()
> endif
>
> Should this cdata (unused afaics) object be removed too?

It seems there are more issues with the doc generation.

Looking at dpdk.org documentation (https://doc.dpdk.org/api/), there
is a dead link to DTS at the bottom of the page:
tests: [DTS]()

The documentation for dts should be generated to dpdk_build_root
/doc/api/html/dts
And I think the link should be a relative one, like
cdata.set('DTS_API_MAIN_PAGE', join_paths('dts', 'index.html'))

Please have a look.

-- 
David Marchand

Re: [PATCH] dts: fix doxygen API link

[Paul Szczepanek]

On 24/10/2024 10:12, David Marchand wrote:
>>
>> Looking again while applying, something is fishy in doc/api/meson.build:
>>
>> if not doxygen.found()
>>   # process DTS API doc build even if DPDK API doc build can't be done
>>   cdata = configuration_data()
>>   subdir('dts')
>>   subdir_done()
>> endif
>>
>> Should this cdata (unused afaics) object be removed too?

Yes, I'm removing this.

> 
> It seems there are more issues with the doc generation.
> 
> Looking at dpdk.org documentation (https://doc.dpdk.org/api/), there
> is a dead link to DTS at the bottom of the page:
> tests: [DTS]()

That's what the original patch addressed.

> 
> The documentation for dts should be generated to dpdk_build_root
> /doc/api/html/dts

Yes, my V2 will fix this and place dts inside API so the website docs work.

> And I think the link should be a relative one, like
> cdata.set('DTS_API_MAIN_PAGE', join_paths('dts', 'index.html'))
> 
> Please have a look.
> 

Thanks. Will send out V2 as soon as it clears local checks.

[PATCH v2] dts: fix doxygen API link and DTS docs placement

[Paul Szczepanek]

Alias used to produce the link to the DTS API docs uses config data.
The required value in config data was being added in the wrong scope.
This moves the key addition to where the config data object is created.

DTS docs need to be placed in the same dir as main API docs.
Made DTS docs dependent on main docs and stopped separate install step
relying instead on the parent docs to install them.
This means they can no longer be build without main docs.

Added a line to sphinx python wrapper to create the destination path
if not already present.

Fixes: 7f9326423a04 ("dts: add API doc generation")

Signed-off-by: Paul Szczepanek <paul.szczepanek@arm.com>
Acked-by: Patrick Robb <probb@iol.unh.edu>
---
 buildtools/call-sphinx-build.py |  3 +++
 doc/api/dts/meson.build         | 12 +++++-------
 doc/api/meson.build             |  7 ++++---
 3 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/buildtools/call-sphinx-build.py b/buildtools/call-sphinx-build.py
index 5810b7c84e..2c7de54285 100755
--- a/buildtools/call-sphinx-build.py
+++ b/buildtools/call-sphinx-build.py
@@ -25,6 +25,9 @@
 for root, dirs, files in os.walk(src):
     srcfiles.extend([join(root, f) for f in files])
 
+# create destination path if not already present
+os.makedirs(dst, exist_ok=True)
+
 # run sphinx, putting the html output in a "html" directory
 with open(join(dst, 'sphinx_html.out'), 'w') as out:
     process = run(sphinx_cmd + ['-b', 'html', src, join(dst, 'html')],
diff --git a/doc/api/dts/meson.build b/doc/api/dts/meson.build
index 5115df7095..fc147f13f3 100644
--- a/doc/api/dts/meson.build
+++ b/doc/api/dts/meson.build
@@ -11,21 +11,19 @@ if python_ver_satisfied != 0
     subdir_done()
 endif
 
-cdata.set('DTS_API_MAIN_PAGE', join_paths('..', 'dts', 'html', 'index.html'))
-
 extra_sphinx_args = ['-E', '-c', join_paths(doc_source_dir, 'guides')]
 if get_option('werror')
     extra_sphinx_args += '-W'
 endif
 
-htmldir = join_paths(get_option('datadir'), 'doc', 'dpdk', 'dts')
+# DTS docs are generated inside main Doxygen docs build directory
+# DTS docs relies on main docs to install it so does not define install dir
 dts_api_html = custom_target('dts_api_html',
+        depends: doxy_html_build,
         output: 'html',
         command: [sphinx_wrapper, sphinx, meson.project_version(),
-            meson.current_source_dir(), meson.current_build_dir(), extra_sphinx_args],
-        build_by_default: get_option('enable_docs'),
-        install: get_option('enable_docs'),
-        install_dir: htmldir)
+            meson.current_source_dir(), join_paths(api_build_dir, 'html', 'dts'), extra_sphinx_args],
+        build_by_default: get_option('enable_docs'))
 
 doc_targets += dts_api_html
 doc_target_names += 'DTS_API_HTML'
diff --git a/doc/api/meson.build b/doc/api/meson.build
index ae23e9825e..f9f1326bbd 100644
--- a/doc/api/meson.build
+++ b/doc/api/meson.build
@@ -4,9 +4,6 @@
 doxygen = find_program('doxygen', required: get_option('enable_docs'))
 
 if not doxygen.found()
-  # process DTS API doc build even if DPDK API doc build can't be done
-  cdata = configuration_data()
-  subdir('dts')
   subdir_done()
 endif
 
@@ -40,6 +37,7 @@ cdata.set('OUTPUT', join_paths(dpdk_build_root, 'doc', 'api'))
 cdata.set('TOPDIR', dpdk_source_root)
 cdata.set('STRIP_FROM_PATH', ' '.join([dpdk_source_root, join_paths(dpdk_build_root, 'doc', 'api')]))
 cdata.set('WARN_AS_ERROR', 'NO')
+cdata.set('DTS_API_MAIN_PAGE', join_paths('.', 'dts', 'html', 'index.html'))
 if get_option('werror')
     cdata.set('WARN_AS_ERROR', 'YES')
 endif
@@ -104,4 +102,7 @@ if mandb.found() and get_option('enable_docs')
     meson.add_install_script(mandb)
 endif
 
+# used by DTS to place its files into
+api_build_dir = meson.current_build_dir()
+
 subdir('dts')
-- 
2.39.2

Re: [PATCH v2] dts: fix doxygen API link and DTS docs placement

[Dean Marx]

[-- Attachment #1: Type: text/plain, Size: 882 bytes --]

On Fri, Oct 25, 2024 at 6:35 AM Paul Szczepanek <paul.szczepanek@arm.com>
wrote:

> Alias used to produce the link to the DTS API docs uses config data.
> The required value in config data was being added in the wrong scope.
> This moves the key addition to where the config data object is created.
>
> DTS docs need to be placed in the same dir as main API docs.
> Made DTS docs dependent on main docs and stopped separate install step
> relying instead on the parent docs to install them.
> This means they can no longer be build without main docs.
>
> Added a line to sphinx python wrapper to create the destination path
> if not already present.
>
> Fixes: 7f9326423a04 ("dts: add API doc generation")
>
> Signed-off-by: Paul Szczepanek <paul.szczepanek@arm.com>
> Acked-by: Patrick Robb <probb@iol.unh.edu>
>

Reviewed-by: Dean Marx <dmarx@iol.unh.edu>

[-- Attachment #2: Type: text/html, Size: 1379 bytes --]

Re: [PATCH v2] dts: fix doxygen API link and DTS docs placement

[Nicholas Pratte]

Reviewed-by: Nicholas Pratte <npratte@iol.unh.edu>

Re: [PATCH v2] dts: fix doxygen API link and DTS docs placement

[Patrick Robb]

[-- Attachment #1: Type: text/plain, Size: 46 bytes --]

Reviewed-by: Patrick Robb <probb@iol.unh.edu>

[-- Attachment #2: Type: text/html, Size: 112 bytes --]