[dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Thomas Monjalon]

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(-)

diff --git a/doc/guides/prog_guide/bbdev.rst b/doc/guides/prog_guide/bbdev.rst
index ef05dcb4c..f023778bd 100644
--- a/doc/guides/prog_guide/bbdev.rst
+++ b/doc/guides/prog_guide/bbdev.rst
@@ -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.
-- 
2.21.0

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Chautru, Nicolas]

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

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Thomas Monjalon]

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?

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[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. 

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Thomas Monjalon]

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.

[dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Nicolas Chautru]

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")

Signed-off-by: Nicolas Chautru <nicolas.chautru@intel.com>
---
 doc/guides/prog_guide/bbdev.rst | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/doc/guides/prog_guide/bbdev.rst b/doc/guides/prog_guide/bbdev.rst
index ef05dcb..6c0bb3c 100644
--- a/doc/guides/prog_guide/bbdev.rst
+++ b/doc/guides/prog_guide/bbdev.rst
@@ -800,21 +800,21 @@ The LDPC encode 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  |
-+----------------+------------+-------------------------------------------------------+
++----------------+--------------------------------------------------------------------+
+|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 |
-+----------------+------------+-------------------------------------------------------+
++----------------+--------------------------------------------------------------------+
+|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`` is mandatory for all BBDEV PMDs and is the
 incoming code block or transport block data.
@@ -865,7 +865,7 @@ calculated by BBDEV before signalling to the driver.
 The number of CBs in the group should not be confused with ``c``, the
 total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2)
 
-Figure 13.1 above showing the Turbo encoding of CBs using BBDEV
+Figure :numref:`figure_turbo_tb_encode` above showing the Turbo encoding of CBs using BBDEV
 interface in TB-mode is also valid for LDPC encode.
 
 BBDEV LDPC Decode Operation
@@ -1077,7 +1077,7 @@ total number of CBs in the full TB (``C`` as per 3GPP TS 38.212 section 5.2.2)
 The ``length`` is total size of the CBs inclusive of any CRC24A and CRC24B in
 case they were appended by the application.
 
-Figure 13.2 above showing the Turbo decoding of CBs using BBDEV
+Figure :numref:`figure_turbo_tb_decode` above showing the Turbo decoding of CBs using BBDEV
 interface in TB-mode is also valid for LDPC decode.
 
 
-- 
1.8.3.1

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Thomas Monjalon]

18/07/2019 08:24, Nicolas Chautru:
> -Figure 13.1 above showing the Turbo encoding of CBs using BBDEV
> +Figure :numref:`figure_turbo_tb_encode` above showing the Turbo encoding of CBs using BBDEV
>  interface in TB-mode is also valid for LDPC encode.
[...]
> -Figure 13.2 above showing the Turbo decoding of CBs using BBDEV
> +Figure :numref:`figure_turbo_tb_decode` above showing the Turbo decoding of CBs using BBDEV
>  interface in TB-mode is also valid for LDPC decode.

3 comments above the change of references:

- there are a lot more, please search for the word "section"

- it deserves a separate commit

- the line length should be below 100 chars, better below 80.
The ideal is to break lines logically after a punctuation sign,
or between "subject" and "verb", etc.
Example:
	Figure :numref:`figure_turbo_tb_encode` above
	showing the Turbo encoding of CBs using BBDEV interface in TB-mode
	is also valid for LDPC encode.

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Chautru, Nicolas]

From: Thomas Monjalon [mailto:thomas@monjalon.net] 
>3 comments above the change of references:
>
>- there are a lot more, please search for the word "section"

All the ones I could see are similar to "as per 3GPP TS 38.212 section 5.2.2" which is does not refer to a section within DPDK documentation but to external 3GPP specs documents. 

>- it deserves a separate commit

OK. And you want such a commit now for 19.09 or later on?

>- the line length should be below 100 chars, better below 80.
>The ideal is to break lines logically after a punctuation sign, or between "subject" and "verb", etc.
>Example:
>	Figure :numref:`figure_turbo_tb_encode` above
>	showing the Turbo encoding of CBs using BBDEV interface in TB-mode
>	is also valid for LDPC encode.

All lines are less than 100 chars, but a few places are >80 chars. Let me know if you want this changed for 19.09 or later. 

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Thomas Monjalon]

18/07/2019 16:43, Chautru, Nicolas:
> From: Thomas Monjalon [mailto:thomas@monjalon.net] 
> >3 comments above the change of references:
> >
> >- there are a lot more, please search for the word "section"
> 
> All the ones I could see are similar to "as per 3GPP TS 38.212 section 5.2.2" which is does not refer to a section within DPDK documentation but to external 3GPP specs documents.

You're right! I completely overlooked it.

> >- it deserves a separate commit
> 
> OK. And you want such a commit now for 19.09 or later on?

Given there are only 2 figure refs, it can stay with PDF fix.

> >- the line length should be below 100 chars, better below 80.
> >The ideal is to break lines logically after a punctuation sign, or between "subject" and "verb", etc.
> >Example:
> >	Figure :numref:`figure_turbo_tb_encode` above
> >	showing the Turbo encoding of CBs using BBDEV interface in TB-mode
> >	is also valid for LDPC encode.
> 
> All lines are less than 100 chars, but a few places are >80 chars. Let me know if you want this changed for 19.09 or later.

The rule is to not do cosmetic change :)
I was explaining the line breaking for the lines you were changing
while fixing figure ref.

I think I will apply this patch and adjust the line breaking if needed.
Is it OK?

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Chautru, Nicolas]

From: Thomas Monjalon [mailto:thomas@monjalon.net] 
>18/07/2019 16:43, Chautru, Nicolas:
>> From: Thomas Monjalon [mailto:thomas@monjalon.net]
>> >3 comments above the change of references:
>> >
>> >- there are a lot more, please search for the word "section"
>> 
>> All the ones I could see are similar to "as per 3GPP TS 38.212 section 5.2.2" which is does not refer to a section within DPDK documentation but to external 3GPP specs documents.
>
>You're right! I completely overlooked it.
>
>> >- it deserves a separate commit
>> 
>> OK. And you want such a commit now for 19.09 or later on?
>
>Given there are only 2 figure refs, it can stay with PDF fix.
>
>> >- the line length should be below 100 chars, better below 80.
>> >The ideal is to break lines logically after a punctuation sign, or between "subject" and "verb", etc.
>> >Example:
>> >	Figure :numref:`figure_turbo_tb_encode` above
>> >	showing the Turbo encoding of CBs using BBDEV interface in TB-mode
>> >	is also valid for LDPC encode.
>> 
>> All lines are less than 100 chars, but a few places are >80 chars. Let me know if you want this changed for 19.09 or later.
>
>The rule is to not do cosmetic change :) I was explaining the line breaking for the lines you were changing while fixing figure ref.
>
>I think I will apply this patch and adjust the line breaking if needed.
>Is it OK?
>

Ok with me. Thanks Thomas.

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Thomas Monjalon]

18/07/2019 08:24, Nicolas Chautru:
> 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")
> 
> Signed-off-by: Nicolas Chautru <nicolas.chautru@intel.com>

Thanks for the quick reaction.
If you agree, I can apply this patch without the changes of figure refs.

About the tables, there are simpler syntax in RsT:
http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables
You can also consider the definition lists:
http://docutils.sourceforge.net/docs/user/rst/quickref.html#definition-lists

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Chautru, Nicolas]

From: Thomas Monjalon [mailto:thomas@monjalon.net] 
>18/07/2019 08:24, Nicolas Chautru:
>> 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")
>> 
>> Signed-off-by: Nicolas Chautru <nicolas.chautru@intel.com>
>
>Thanks for the quick reaction.
>If you agree, I can apply this patch without the changes of figure refs.

No problem, we can fix the other cosmetic changes that you have raised post 19.09. 

>About the tables, there are simpler syntax in RsT:
>http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables

To be honest, I cannot see the problem with the current format which is following that structure already. 
What error message do you get on your machine? This is not caught on DPDK CI, is it? 

>You can also consider the definition lists:
>http://docutils.sourceforge.net/docs/user/rst/quickref.html#definition-lists

Clearer has a formal table from my point of view. 

Thanks

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Thomas Monjalon]

18/07/2019 16:51, Chautru, Nicolas:
> From: Thomas Monjalon [mailto:thomas@monjalon.net] 
> >About the tables, there are simpler syntax in RsT:
> >http://docutils.sourceforge.net/docs/user/rst/quickref.html#tables
> 
> To be honest, I cannot see the problem with the current format which is following that structure already. 

You are using the grid table syntax.
I was referring to the simple table syntax as below:

	=====  =====  ======
	   Inputs     Output
	------------  ------
	  A      B    A or B
	=====  =====  ======
	False  False  False
	True   False  True
	False  True   True
	True   True   True
	=====  =====  ======

> What error message do you get on your machine?

That's the difficult thing with PDF build, we do not have
any clear error message. I had to bisect to find the root cause.

> This is not caught on DPDK CI, is it?

No and I cannot reproduce it on my laptop.
I see the failure only on dpdk.org which has a different OS version.

> >You can also consider the definition lists:
> >http://docutils.sourceforge.net/docs/user/rst/quickref.html#definition-lists
> 
> Clearer has a formal table from my point of view.

Yes maybe, it depends on what we want to document.

Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide

[Thomas Monjalon]

18/07/2019 08:24, Nicolas Chautru:
> 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")
> 
> Signed-off-by: Nicolas Chautru <nicolas.chautru@intel.com>
> ---
> --- a/doc/guides/prog_guide/bbdev.rst
> +++ b/doc/guides/prog_guide/bbdev.rst
> -+----------------+------------+-------------------------------------------------------+
> -|                |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       |
> -+----------------+------------+-------------------------------------------------------+
> ++----------------+--------------------------------------------------------------------+
> +|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                    |
> ++----------------+--------------------------------------------------------------------+

Actually the problem is still here: the table line is "+" instead of "|".
I'll fix it, keeping the original format.