[dpdk-dev] [PATCH v1] doc: autogenerate nic overview table from ini files
> -Original Message- > From: Thomas Monjalon [mailto:thomas.monjalon at 6wind.com] > Sent: Thursday, June 30, 2016 7:25 PM > To: Mcnamara, John > Cc: dev at dpdk.org > Subject: Re: [dpdk-dev] [PATCH v1] doc: autogenerate nic overview table > from ini files > > 2016-06-30 19:03, John McNamara: > > This patch converts the NIC feature table in the overview doc into a > > set of ini files and adds some functions into the Sphinx conf.py file > > to convert them back into an RST table. > > > Would it be possible to make it a bit more generic and reusable to > generate other tables of this kind? It would be possible (in the technical sense) but probably not worth the effort. :-) > > * Blank entries in the PMD ini files are optional. They will get a > default > > blank entry in the RST table based on the entries in the default.ini > file. > > The ini files in this patch were generated programmatically from the > > original RST table. > > I don't think there is a benefit to have blank entries in the .ini file. > And there would be less conflicts if the guideline was to avoid blank > entries when adding a new feature. I can generate a set of ini files without blank entries if that is the preference. For some PMDs that will mean that there are no entries in the file, apart from the heading, but I guess that is okay. I'll change that in v2. > > PDF output is restrictive :) Yes, and the PDF infrastructure is a bit of a pain but we still get a lot of people in the field who like them and ask for them after releases. Maybe they read them on the beach, on holidays. John
[dpdk-dev] [PATCH v1] doc: autogenerate nic overview table from ini files
On Thu, Jun 30, 2016 at 08:25:14PM +0200, Thomas Monjalon wrote: > 2016-06-30 19:03, John McNamara: > > This patch converts the NIC feature table in the overview doc into a set of > > ini files and adds some functions into the Sphinx conf.py file to convert > > them > > back into an RST table. > > > > The reason for doing this is to make it easier for PMD maintainers to update > > the feature matrix that makes up the table and to avoid frequent and hard to > > resolve conflicts in doc/guides/nics/overview.rst. > > Great idea! Yes, indeed! The old formats also make the review hard (due to the long/messy diff). I was also kidding/wishing before that it'd be great if we could have a column-based diff file. With your proposal, we don't need it any more :) --yliu
[dpdk-dev] [PATCH v1] doc: autogenerate nic overview table from ini files
2016-06-30 19:03, John McNamara: > This patch converts the NIC feature table in the overview doc into a set of > ini files and adds some functions into the Sphinx conf.py file to convert them > back into an RST table. > > The reason for doing this is to make it easier for PMD maintainers to update > the feature matrix that makes up the table and to avoid frequent and hard to > resolve conflicts in doc/guides/nics/overview.rst. Great idea! Would it be possible to make it a bit more generic and reusable to generate other tables of this kind? > * In order to avoid the merge conflict issue noted above the RST table is now > in an external RST include file and excluded from the repo via .gitignore. It would be better to generate the rst file in the build directory. But I guess it makes sphinx build more difficult. > * Blank entries in the PMD ini files are optional. They will get a default > blank entry in the RST table based on the entries in the default.ini file. > The ini files in this patch were generated programmatically from the > original RST table. I don't think there is a benefit to have blank entries in the .ini file. And there would be less conflicts if the guideline was to avoid blank entries when adding a new feature. > > * I would like to extend this to produce a pure Html table with rotated column > headers like this: https://css-tricks.com/rotated-table-column-headers/ > I tried to get this to work within the current RST + CSS preamble but > failed. Nice > * I would also like to extend this to produce a table, or more likely a number > of tables, that would display the same information in the PDF document > without going off the page. PDF output is restrictive :)
[dpdk-dev] [PATCH v1] doc: autogenerate nic overview table from ini files
Convert the NIC feature table in the overview doc into a set of ini files and add functions into the Sphinx conf.py file to auto-generate them back into an RST table. The reason for doing this is to make it easier for PMD maintainers to update the feature matrix that makes up the table and to avoid frequent and hard to resolve conflicts in doc/guides/nics/overview.rst. A NIC/PMD feature matrix is now an ini file like the following: $ head doc/guides/nics/nic_features/i40e.ini ; ; Features of the i40e network driver. ; [Features] Speed capabilities = Link status = Y Link status event= Y Queue status event = Rx interrupt = Y Queue start/stop = Y ... The output RST table matches the existing table with the column headers sorted. Signed-off-by: John McNamara --- .gitignore | 2 + doc/guides/conf.py | 155 +++ doc/guides/nics/nic_features/afpacket.ini| 64 +++ doc/guides/nics/nic_features/bnx2x.ini | 64 +++ doc/guides/nics/nic_features/bnx2x_vf.ini| 64 +++ doc/guides/nics/nic_features/bnxt.ini| 64 +++ doc/guides/nics/nic_features/bonding.ini | 64 +++ doc/guides/nics/nic_features/cxgbe.ini | 64 +++ doc/guides/nics/nic_features/default.ini | 68 doc/guides/nics/nic_features/e1000.ini | 64 +++ doc/guides/nics/nic_features/ena.ini | 64 +++ doc/guides/nics/nic_features/enic.ini| 64 +++ doc/guides/nics/nic_features/fm10k.ini | 64 +++ doc/guides/nics/nic_features/fm10k_vec.ini | 64 +++ doc/guides/nics/nic_features/fm10k_vf.ini| 64 +++ doc/guides/nics/nic_features/fm10kvf_vec.ini | 64 +++ doc/guides/nics/nic_features/i40e.ini| 64 +++ doc/guides/nics/nic_features/i40e_vec.ini| 64 +++ doc/guides/nics/nic_features/i40e_vf.ini | 64 +++ doc/guides/nics/nic_features/i40evf_vec.ini | 64 +++ doc/guides/nics/nic_features/igb.ini | 64 +++ doc/guides/nics/nic_features/igb_vf.ini | 64 +++ doc/guides/nics/nic_features/ixgbe.ini | 64 +++ doc/guides/nics/nic_features/ixgbe_vec.ini | 64 +++ doc/guides/nics/nic_features/ixgbe_vf.ini| 64 +++ doc/guides/nics/nic_features/ixgbevf_vec.ini | 64 +++ doc/guides/nics/nic_features/mlx4.ini| 64 +++ doc/guides/nics/nic_features/mlx5.ini| 64 +++ doc/guides/nics/nic_features/mpipe.ini | 64 +++ doc/guides/nics/nic_features/nfp.ini | 64 +++ doc/guides/nics/nic_features/null.ini| 64 +++ doc/guides/nics/nic_features/pcap.ini| 64 +++ doc/guides/nics/nic_features/qede.ini| 64 +++ doc/guides/nics/nic_features/qede_vf.ini | 64 +++ doc/guides/nics/nic_features/ring.ini| 64 +++ doc/guides/nics/nic_features/szedata2.ini| 64 +++ doc/guides/nics/nic_features/thunderx.ini| 64 +++ doc/guides/nics/nic_features/vhost.ini | 64 +++ doc/guides/nics/nic_features/virtio.ini | 64 +++ doc/guides/nics/nic_features/virtio_vec.ini | 64 +++ doc/guides/nics/nic_features/vmxnet3.ini | 64 +++ doc/guides/nics/nic_features/xenvirt.ini | 64 +++ doc/guides/nics/overview.rst | 77 + 43 files changed, 2723 insertions(+), 75 deletions(-) create mode 100644 doc/guides/nics/nic_features/afpacket.ini create mode 100644 doc/guides/nics/nic_features/bnx2x.ini create mode 100644 doc/guides/nics/nic_features/bnx2x_vf.ini create mode 100644 doc/guides/nics/nic_features/bnxt.ini create mode 100644 doc/guides/nics/nic_features/bonding.ini create mode 100644 doc/guides/nics/nic_features/cxgbe.ini create mode 100644 doc/guides/nics/nic_features/default.ini create mode 100644 doc/guides/nics/nic_features/e1000.ini create mode 100644 doc/guides/nics/nic_features/ena.ini create mode 100644 doc/guides/nics/nic_features/enic.ini create mode 100644 doc/guides/nics/nic_features/fm10k.ini create mode 100644 doc/guides/nics/nic_features/fm10k_vec.ini create mode 100644 doc/guides/nics/nic_features/fm10k_vf.ini create mode 100644 doc/guides/nics/nic_features/fm10kvf_vec.ini create mode 100644 doc/guides/nics/nic_features/i40e.ini create mode 100644 doc/guides/nics/nic_features/i40e_vec.ini create mode 100644 doc/guides/nics/nic_features/i40e_vf.ini create mode 100644 doc/guides/nics/nic_features/i40evf_vec.ini create mode 100644 doc/guides/nics/nic_features/igb.ini create mode 100644 doc/guides/nics/nic_features/igb_vf.ini create mode 100644 doc/guides/nics/nic_features/ixgbe.ini create mode 100644 doc/guides/nics/nic_features/ixgbe_vec.ini
[dpdk-dev] [PATCH v1] doc: autogenerate nic overview table from ini files
This patch converts the NIC feature table in the overview doc into a set of ini files and adds some functions into the Sphinx conf.py file to convert them back into an RST table. The reason for doing this is to make it easier for PMD maintainers to update the feature matrix that makes up the table and to avoid frequent and hard to resolve conflicts in doc/guides/nics/overview.rst. A NIC/PMD feature matrix is now an ini file like the following: $ head doc/guides/nics/nic_features/i40e.ini ; ; Features of the i40e network driver. ; [Features] Speed capabilities = Link status = Y Link status event= Y Queue status event = Rx interrupt = Y Queue start/stop = Y ... The output RST table matches the existing table with the column headers sorted. Notes: * In order to avoid the merge conflict issue noted above the RST table is now in an external RST include file and excluded from the repo via .gitignore. * The order of the features in the table is controlled by a 'default.ini' file. This also determines what are the allowable features in all other ini files. This also catches typos or non-default new entries. * Blank entries in the PMD ini files are optional. They will get a default blank entry in the RST table based on the entries in the default.ini file. The ini files in this patch were generated programmatically from the original RST table. * I tried to put the Python code in a sub-module called from the Sphinx conf.py but I could only get that to work in Sphinx 1.4.4. So, for now, the code has been added to conf.py. * I would like to extend this to produce a pure Html table with rotated column headers like this: https://css-tricks.com/rotated-table-column-headers/ I tried to get this to work within the current RST + CSS preamble but failed. * I would also like to extend this to produce a table, or more likely a number of tables, that would display the same information in the PDF document without going off the page. John McNamara (1): doc: autogenerate nic overview table from ini files .gitignore | 2 + doc/guides/conf.py | 155 +++ doc/guides/nics/nic_features/afpacket.ini| 64 +++ doc/guides/nics/nic_features/bnx2x.ini | 64 +++ doc/guides/nics/nic_features/bnx2x_vf.ini| 64 +++ doc/guides/nics/nic_features/bnxt.ini| 64 +++ doc/guides/nics/nic_features/bonding.ini | 64 +++ doc/guides/nics/nic_features/cxgbe.ini | 64 +++ doc/guides/nics/nic_features/default.ini | 68 doc/guides/nics/nic_features/e1000.ini | 64 +++ doc/guides/nics/nic_features/ena.ini | 64 +++ doc/guides/nics/nic_features/enic.ini| 64 +++ doc/guides/nics/nic_features/fm10k.ini | 64 +++ doc/guides/nics/nic_features/fm10k_vec.ini | 64 +++ doc/guides/nics/nic_features/fm10k_vf.ini| 64 +++ doc/guides/nics/nic_features/fm10kvf_vec.ini | 64 +++ doc/guides/nics/nic_features/i40e.ini| 64 +++ doc/guides/nics/nic_features/i40e_vec.ini| 64 +++ doc/guides/nics/nic_features/i40e_vf.ini | 64 +++ doc/guides/nics/nic_features/i40evf_vec.ini | 64 +++ doc/guides/nics/nic_features/igb.ini | 64 +++ doc/guides/nics/nic_features/igb_vf.ini | 64 +++ doc/guides/nics/nic_features/ixgbe.ini | 64 +++ doc/guides/nics/nic_features/ixgbe_vec.ini | 64 +++ doc/guides/nics/nic_features/ixgbe_vf.ini| 64 +++ doc/guides/nics/nic_features/ixgbevf_vec.ini | 64 +++ doc/guides/nics/nic_features/mlx4.ini| 64 +++ doc/guides/nics/nic_features/mlx5.ini| 64 +++ doc/guides/nics/nic_features/mpipe.ini | 64 +++ doc/guides/nics/nic_features/nfp.ini | 64 +++ doc/guides/nics/nic_features/null.ini| 64 +++ doc/guides/nics/nic_features/pcap.ini| 64 +++ doc/guides/nics/nic_features/qede.ini| 64 +++ doc/guides/nics/nic_features/qede_vf.ini | 64 +++ doc/guides/nics/nic_features/ring.ini| 64 +++ doc/guides/nics/nic_features/szedata2.ini| 64 +++ doc/guides/nics/nic_features/thunderx.ini| 64 +++ doc/guides/nics/nic_features/vhost.ini | 64 +++ doc/guides/nics/nic_features/virtio.ini | 64 +++ doc/guides/nics/nic_features/virtio_vec.ini | 64 +++ doc/guides/nics/nic_features/vmxnet3.ini | 64 +++ doc/guides/nics/nic_features/xenvirt.ini | 64 +++ doc/guides/nics/overview.rst | 77 + 43 files changed, 2723 insertions(+), 75 deletions(-) create mode 100644
