Skip to contentSkip to conversation

Remove [Description] subtitle from docparse

RFC Petr Vorel 3 participants 7 messages Jan 31, 2025

lore
Share & tools
lore

Petr Vorel

author
#0 lore raw

Hi,

Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.

1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).

I would keep other subtitles (e.g. [Algorithm]), just remove the first one.

Kind regards,
Petr

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
#1 lore raw

Hi Petr,

I'm currently working on parsing metadata in order to produce a tests list in the LTP documentation. I just replace "[Description]" with "**Description**". Same for "[Algorithm]".

I would keep the bold version tho, with the double star **.

Andrea

Quoted 13 lines · Petr Vorel

Hi,

Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.

1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).

I would keep other subtitles (e.g. [Algorithm]), just remove the first one.

Kind regards,
Petr

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
author
#2 lore raw

Hi Andrea,

Quoted 4 lines

Hi Petr,

I'm currently working on parsing metadata in order to produce a tests list in the LTP documentation.

FYI I planned to work on it (announced in ML [1]), but since you started I stop working on it.

Quoted 4 lines

I just replace "[Description]" with "**Description**". Same for "[Algorithm]".

I would keep the bold version tho, with the double star **.

We talk about a different things. You about the conversion of the subtitles to the final documentation (previously was done in docparse/testinfo.pl, now you will do it in python).

But I'm suggesting to entirely remove subtitle "Description". It looks to me useless and some people don't add it thus docs looks inconsistent.

Kind regards,
Petr

Quoted 15 lines

Andrea

Quoted 12 lines · Petr Vorel

Hi,

Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.

1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).

I would keep other subtitles (e.g. [Algorithm]), just remove the first one.

Kind regards,
Petr

[1] https://lore.kernel.org/ltp/20241227073921.GB290415@pevik/

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
#3 lore raw
Quoted 7 lines · Petr Vorel

Hi Andrea,

Quoted 3 lines

Hi Petr,
I'm currently working on parsing metadata in order to produce a tests list in the LTP documentation.

FYI I planned to work on it (announced in ML [1]), but since you started I stop working on it.

I'm sorry, I didn't read carefully. The results will come out soon tho, I will send the patch-set soon.

Quoted 10 lines
Quoted 4 lines

I just replace "[Description]" with "**Description**". Same for "[Algorithm]".
I would keep the bold version tho, with the double star **.

We talk about a different things. You about the conversion of the subtitles to the final documentation (previously was done in docparse/testinfo.pl, now you will do it in python).

But I'm suggesting to entirely remove subtitle "Description". It looks to me useless and some people don't add it thus docs looks inconsistent.

The thing is that there's not only [Description], but there's also [Algorithm]. Maybe we can think about the tests description as a whole RST code that will be injected inside the documentation website once it's published. In this way, conversion would be much easier.

Quoted 13 lines

Kind regards,
Petr

Quoted 10 lines

Andrea

Quoted 8 lines · Petr Vorel

Hi,
Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.
1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).
I would keep other subtitles (e.g. [Algorithm]), just remove the first one. Kind regards,
Petr

Quoted 1 line

[1] https://lore.kernel.org/ltp/20241227073921.GB290415@pevik/

Andrea

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
author
#4 lore raw

Hi Andrea,

Quoted 10 lines · Petr Vorel
Quoted 7 lines

Hi Andrea,

Quoted 3 lines

Hi Petr,
I'm currently working on parsing metadata in order to produce a tests list in the LTP documentation.

FYI I planned to work on it (announced in ML [1]), but since you started I stop working on it.

I'm sorry, I didn't read carefully. The results will come out soon tho, I will send the patch-set soon.

Not a big deal, just sometimes it might happen more people are implementing the same thing.

Quoted 7 lines
Quoted 6 lines
Quoted 3 lines

I just replace "[Description]" with "**Description**". Same for "[Algorithm]".
I would keep the bold version tho, with the double star **.

We talk about a different things. You about the conversion of the subtitles to the final documentation (previously was done in docparse/testinfo.pl, now you will do it in python).

Quoted 6 lines
Quoted 2 lines

But I'm suggesting to entirely remove subtitle "Description". It looks to me useless and some people don't add it thus docs looks inconsistent.

The thing is that there's not only [Description], but there's also [Algorithm]. Maybe we can think about the tests description as a whole RST code that will be injected inside the documentation website once it's published. In this way, conversion would be much easier.

As I wrote to Cyril:
The reason why suggested to remove it is that I don't see much information value in "Description" title. "Algorithm" has at least little bit of information value.

Besides these two we have only:
* [Prerequisites] (testcases/kernel/mem/ksm/ksm07.c)
* [Race Description] (testcases/kernel/syscalls/fork/fork13.c)

Kind regards,
Petr

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
#5 lore raw
In reply to Petr Vorel

Hi!

Quoted 5 lines

Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.

1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).

That part can be fixed with something as:

metadata/metaparse.c +8 -0
index 2b96149dc..422604a2c 100644
@@ -852,6 +852,14 @@ static struct data_node *parse_file(const char *fname)
 
        if (data_node_array_len(doc)) {
                data_node_hash_add(res, "doc", doc);
+
+               char *str = doc->array.array[0]->string.val;
+
+               if (!strstr("[Description]", str)) {
+                       fprintf(stderr, "%s: Missing [Description] in doc comment!\n", fname);
+                       exit(1);
+               }
+
                found = 1;
        } else {
                data_node_free(doc);
Quoted 1 line

I would keep other subtitles (e.g. [Algorithm]), just remove the first one.

I find it a bit inconsistent if we do it this way, but I guess either way is fine.

Signature · 5 lines
Cyril Hrubis
[email protected]

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp
author
#6 lore raw
Quoted 18 lines

Hi!

Quoted 5 lines

Can we remove [Description] part from docparse documentation in tests? This is transformed into "Description" subtitle in resulted html/pdf.

1) It's not really needed (it's obvious that it's a description of the test)
2) Sometimes it's missing (inconsistency).

That part can be fixed with something as:

metadata/metaparse.c +1 -0
index 2b96149dc..422604a2c 100644
@@ -852,6 +852,14 @@ static struct data_node *parse_file(const char *fname)
 
        if (data_node_array_len(doc)) {
                data_node_hash_add(res, "doc", doc);
+

metadata/metaparse.c static struct data_node *parse_file(const char *fname) · line 865

Quoted 10 lines
metadata/metaparse.c +7 -0
+               char *str = doc->array.array[0]->string.val;
+
+               if (!strstr("[Description]", str)) {
+                       fprintf(stderr, "%s: Missing [Description] in doc comment!\n", fname);
+                       exit(1);
+               }
+
                found = 1;
        } else {
                data_node_free(doc);

Sure, that could work as well.

Quoted 4 lines
Quoted 1 line

I would keep other subtitles (e.g. [Algorithm]), just remove the first one.

I find it a bit inconsistent if we do it this way, but I guess either way is fine.

The reason why suggested to remove it is that I don't see much information value in "Description" title. "Algorithm" has at least little bit of information value.

Besides these two we have only:
* [Prerequisites] (testcases/kernel/mem/ksm/ksm07.c)
* [Race Description] (testcases/kernel/syscalls/fork/fork13.c)

Kind regards,
Petr

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp