doc: fix PDF build of bbdev prog guide
Checks
Commit Message
Some machine (like on dpdk.org) may fail to build the prog guide PDF
because of the complex table inserted in the bbdev chapter.
Fixes: 3f3f608142cf ("doc: update bbdev guide for 5GNR operations")
Cc: nicolas.chautru@intel.com
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
Anyway all the documentation about the API details should be removed.
The guide is expected to give an understanding of the whole design,
not replacing the details maintained in the doxygen comments.
While at refactoring this chapter, the hardcoded references to some
section or figure numbers must be replaced by dynamic references.
None of this cleanup is done in this patch.
Please try to rework it quickly before 19.08-rc2,
otherwise this patch will be applied to avoid being annoyed again
(as for -rc1) when generating the documentation on dpdk.org.
---
doc/guides/prog_guide/bbdev.rst | 16 ----------------
1 file changed, 16 deletions(-)
Comments
From: Thomas Monjalon [mailto:thomas@monjalon.net]
>Some machine (like on dpdk.org) may fail to build the prog guide PDF because of the complex table inserted in the bbdev chapter.
>
>Fixes: 3f3f608142cf ("doc: update bbdev guide for 5GNR operations")
>Cc: nicolas.chautru@intel.com
>
>Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
>---
>Anyway all the documentation about the API details should be removed.
>The guide is expected to give an understanding of the whole design, not replacing the details maintained in the doxygen comments.
Thanks Thomas.
These tables are arguably useful on that page with the related contextual verbose information aside which provide more context usage. Still I am reformatting into simpler table structure.
I have just pushed a parallel patch here : https://patches.dpdk.org/patch/56715/
>While at refactoring this chapter, the hardcoded references to some section or figure numbers must be replaced by dynamic references.
I have seen a couple of hardcoded figure numbers which I fixed. Let me know in case I missed some.
Thanks
18/07/2019 15:33, Chautru, Nicolas:
> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> >Anyway all the documentation about the API details should be removed.
> >The guide is expected to give an understanding of the whole design, not replacing the details maintained in the doxygen comments.
>
> Thanks Thomas.
> These tables are arguably useful on that page with the related contextual verbose information aside which provide more context usage. Still I am reformatting into simpler table structure.
> I have just pushed a parallel patch here : https://patches.dpdk.org/patch/56715/
Sorry, I am not sure to understand.
You want to keep all this information?
As I said, most of this guide may be removed
because it is redundant with what we should have in doxygen:
http://doc.dpdk.org/api/rte__bbdev_8h.html
Do you need to add more information in doxygen?
From: Thomas Monjalon [mailto:thomas@monjalon.net]
>18/07/2019 15:33, Chautru, Nicolas:
>> From: Thomas Monjalon [mailto:thomas@monjalon.net]
>> >Anyway all the documentation about the API details should be removed.
>> >The guide is expected to give an understanding of the whole design, not replacing the details maintained in the doxygen comments.
>>
>> Thanks Thomas.
>> These tables are arguably useful on that page with the related contextual verbose information aside which provide more context usage. Still I am reformatting into simpler table structure.
>> I have just pushed a parallel patch here :
>> https://patches.dpdk.org/patch/56715/
>
>Sorry, I am not sure to understand.
>You want to keep all this information?
I would rather yes. I can see your point with some redundancy between code and documentation, but the bbdev.rst documentation is arguably clearer as it is : the detailed information in paragraphs puts into context some of the information captured in a nice and concise table. Clearer than having to go back and forth in doxygen capturing some of this in a less compact format (which still has its own complementary value). Matter of opinion, let me know if you have a fundamental concern with keeping such table in that document.
18/07/2019 16:59, Chautru, Nicolas:
> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> >18/07/2019 15:33, Chautru, Nicolas:
> >> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> >> >Anyway all the documentation about the API details should be removed.
> >> >The guide is expected to give an understanding of the whole design, not replacing the details maintained in the doxygen comments.
> >>
> >> Thanks Thomas.
> >> These tables are arguably useful on that page with the related contextual verbose information aside which provide more context usage. Still I am reformatting into simpler table structure.
> >> I have just pushed a parallel patch here :
> >> https://patches.dpdk.org/patch/56715/
> >
> >Sorry, I am not sure to understand.
> >You want to keep all this information?
>
> I would rather yes. I can see your point with some redundancy between code and documentation, but the bbdev.rst documentation is arguably clearer as it is : the detailed information in paragraphs puts into context some of the information captured in a nice and concise table. Clearer than having to go back and forth in doxygen capturing some of this in a less compact format (which still has its own complementary value). Matter of opinion, let me know if you have a fundamental concern with keeping such table in that document.
I am not sure it is clearer to document all parameters in rst.
The main concern is about maintainability.
When we change something in the code, we change the doxygen
and we forget the rst guide.
The other concern is that maybe the doxygen is not complete.
My advice is to reference the doxygen when the information is the same.
@@ -1008,22 +1008,6 @@ The LDPC decode parameters are set out in the table below.
+----------------+--------------------------------------------------------------------+
|op_flags |bitmask of all active operation capabilities |
+----------------+--------------------------------------------------------------------+
-|**cb_params** |code block specific parameters (code block mode only) |
-+----------------+------------+-------------------------------------------------------+
-| |e |E, length of the rate matched output sequence in bits |
-+----------------+------------+-------------------------------------------------------+
-|**tb_params** | transport block specific parameters (transport block mode only) |
-+----------------+------------+-------------------------------------------------------+
-| |c |number of CBs in the TB or partial TB |
-+----------------+------------+-------------------------------------------------------+
-| |r |index of the first CB in the inbound mbuf data |
-+----------------+------------+-------------------------------------------------------+
-| |c_ab |number of CBs that use Ea before switching to Eb |
-+----------------+------------+-------------------------------------------------------+
-| |ea |Ea, length of the RM output sequence in bits, r < cab |
-+----------------+------------+-------------------------------------------------------+
-| |eb |Eb, length of the RM output sequence in bits r >= cab |
-+----------------+------------+-------------------------------------------------------+
The mbuf input ``input`` encoded CB data is mandatory for all BBDEV PMDs
and is the Virtual Circular Buffer data stream with null padding.