[LTP] [PATCH 1/1] doc: Link struct tst_test and tst_tag

[LTP] [PATCH 1/1] doc: Link struct tst_test and tst_tag

[Petr Vorel]

Although it's currently impossible to link to tst_test members,
it's still useful to make links to allow user to read the actual code.

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
 doc/conf.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/conf.py b/doc/conf.py
index 2be847d90b..8cc890fcc8 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -286,7 +286,7 @@ def _generate_tags_table(tags):
             tag_val = f'`{tag_val} <{tag_url}{tag_val}>`_'
 
         table.extend([
-            f'   * - {tag_key}',
+            f'   * - :c:struct:`{tag_key} <tst_tag>`',
             f'     - {tag_val}',
         ])
 
@@ -331,6 +331,7 @@ def _generate_table_cell(key, values):
     Generate a cell which can be multiline if value is a list.
     """
     cell = []
+    key = f' :c:struct:`{key} <tst_test>`'
 
     if len(values) > 1:
         cell.extend([
-- 
2.47.2


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 1/1] doc: Link struct tst_test and tst_tag

[Andrea Cervesato via ltp]

Hi,

mmh..result looks really weird. Basically every table item is a link to 
tst_test. Did you check if it's possible to extend the struct parser in 
order to have a link for each attribute?

Andrea

On 2/19/25 17:01, Petr Vorel wrote:
> Although it's currently impossible to link to tst_test members,
> it's still useful to make links to allow user to read the actual code.
>
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
>   doc/conf.py | 3 ++-
>   1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/doc/conf.py b/doc/conf.py
> index 2be847d90b..8cc890fcc8 100644
> --- a/doc/conf.py
> +++ b/doc/conf.py
> @@ -286,7 +286,7 @@ def _generate_tags_table(tags):
>               tag_val = f'`{tag_val} <{tag_url}{tag_val}>`_'
>   
>           table.extend([
> -            f'   * - {tag_key}',
> +            f'   * - :c:struct:`{tag_key} <tst_tag>`',
>               f'     - {tag_val}',
>           ])
>   
> @@ -331,6 +331,7 @@ def _generate_table_cell(key, values):
>       Generate a cell which can be multiline if value is a list.
>       """
>       cell = []
> +    key = f' :c:struct:`{key} <tst_test>`'
>   
>       if len(values) > 1:
>           cell.extend([

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 1/1] doc: Link struct tst_test and tst_tag

[Petr Vorel]

Hi Andrea,

> Hi,

> mmh..result looks really weird. Basically every table item is a link to
> tst_test. Did you check if it's possible to extend the struct parser in
> order to have a link for each attribute?

I was although thinking about it, but haven't checked the code. I suppose you'll
be much faster than me with this as you're more familiar with sphinx. I gave up
because reader is nearly at the correct location.

I suppose missing code needs to be done in linuxdoc.rstKernelDoc extension.
Because although it's possible to link to the member in linuxdoc.rstKernelDoc 
(e.g. &tst_test.needs_root), but it leads to "struct tst_test" [1] definition,
which has only anchors for Definitions [2] and Members [3]. I guess it's somehow
possible to link it via C domain [4], but it's not used in linuxdoc.rstKernelDoc
extension.

I tried linuxdoc [5] update to the latest 20240924 (not much changes anyway),
but members still do not have id sections.

Kind regards,
Petr

[1] https://linux-test-project.readthedocs.io/en/latest/developers/api_c_tests.html#struct-tst-test
[2] https://linux-test-project.readthedocs.io/en/latest/developers/api_c_tests.html#tst-test-definition
[3] https://linux-test-project.readthedocs.io/en/latest/developers/api_c_tests.html#tst-test-members
[4] https://www.sphinx-doc.org/en/master/usage/domains/c.html#role-c-var
[5] https://github.com/return42/linuxdoc.git

> Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 1/1] doc: Link struct tst_test and tst_tag

[Andrea Cervesato via ltp]

Hi Petr,

On 2/21/25 00:00, Petr Vorel wrote:
> I was although thinking about it, but haven't checked the code. I suppose you'll
> be much faster than me with this as you're more familiar with sphinx. I gave up
> because reader is nearly at the correct location.
>
> I suppose missing code needs to be done in linuxdoc.rstKernelDoc extension.
> Because although it's possible to link to the member in linuxdoc.rstKernelDoc
> (e.g. &tst_test.needs_root), but it leads to "struct tst_test" [1] definition,
> which has only anchors for Definitions [2] and Members [3]. I guess it's somehow
> possible to link it via C domain [4], but it's not used in linuxdoc.rstKernelDoc
> extension.
>
> I tried linuxdoc [5] update to the latest 20240924 (not much changes anyway),
> but members still do not have id sections.
>
> Kind regards,
> Petr
>
> [1]https://linux-test-project.readthedocs.io/en/latest/developers/api_c_tests.html#struct-tst-test
> [2]https://linux-test-project.readthedocs.io/en/latest/developers/api_c_tests.html#tst-test-definition
> [3]https://linux-test-project.readthedocs.io/en/latest/developers/api_c_tests.html#tst-test-members
> [4]https://www.sphinx-doc.org/en/master/usage/domains/c.html#role-c-var
> [5]https://github.com/return42/linuxdoc.git
>
>> Andrea

Thanks for the references, I took a look at it. It doesn't seem to be 
supported unless we change the code base of kerneldoc. I don't know if 
the effort is worth the result honestly. And the reference to tst_test 
for each struct attribute is a bit an overkill.

Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 1/1] doc: Link struct tst_test and tst_tag

[Petr Vorel]

> Hi Petr,

> On 2/21/25 00:00, Petr Vorel wrote:
> > I was although thinking about it, but haven't checked the code. I suppose you'll
> > be much faster than me with this as you're more familiar with sphinx. I gave up
> > because reader is nearly at the correct location.

> > I suppose missing code needs to be done in linuxdoc.rstKernelDoc extension.
> > Because although it's possible to link to the member in linuxdoc.rstKernelDoc
> > (e.g. &tst_test.needs_root), but it leads to "struct tst_test" [1] definition,
> > which has only anchors for Definitions [2] and Members [3]. I guess it's somehow
> > possible to link it via C domain [4], but it's not used in linuxdoc.rstKernelDoc
> > extension.

> > I tried linuxdoc [5] update to the latest 20240924 (not much changes anyway),
> > but members still do not have id sections.

> > Kind regards,
> > Petr

> > [1]https://linux-test-project.readthedocs.io/en/latest/developers/api_c_tests.html#struct-tst-test
> > [2]https://linux-test-project.readthedocs.io/en/latest/developers/api_c_tests.html#tst-test-definition
> > [3]https://linux-test-project.readthedocs.io/en/latest/developers/api_c_tests.html#tst-test-members
> > [4]https://www.sphinx-doc.org/en/master/usage/domains/c.html#role-c-var
> > [5]https://github.com/return42/linuxdoc.git

> > > Andrea

> Thanks for the references, I took a look at it. It doesn't seem to be
> supported unless we change the code base of kerneldoc. I don't know if the
> effort is worth the result honestly. And the reference to tst_test for each
> struct attribute is a bit an overkill.

Well, I disagree it's an overkill. It help people to quickly see the related
structure. Also, structure members are just pretty close to the section of the
link.

Kind regards,
Petr

> Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 1/1] doc: Link struct tst_test and tst_tag

[Andrea Cervesato via ltp]

On 2/21/25 10:23, Petr Vorel wrote:
> Well, I disagree it's an overkill. It help people to quickly see the related
> structure. Also, structure members are just pretty close to the section of the
> link.
>
> Kind regards,
> Petr

I guess we don't have much other options with the current tools, so feel 
free to merge.

Acked-by: Andrea Cervesato <andrea.cervesato@suse.com>


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 1/1] doc: Link struct tst_test and tst_tag

[Petr Vorel]

> On 2/21/25 10:23, Petr Vorel wrote:
> > Well, I disagree it's an overkill. It help people to quickly see the related
> > structure. Also, structure members are just pretty close to the section of the
> > link.

> > Kind regards,
> > Petr

> I guess we don't have much other options with the current tools, so feel
> free to merge.

+1, I don't expect we both have enough time to dive into linuxdoc / sphinx
internals unless something more important forces us :(.

> Acked-by: Andrea Cervesato <andrea.cervesato@suse.com>

Thanks, merged!

Kind regards,
Petr

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp