[dpdk-dev] [PATCH] doc: move rel_notes instructions as comments

[dpdk-dev] [PATCH] doc: move rel_notes instructions as comments

[Olivier Matz]

We don't want to have this instructions in the generated docs, so use
comments. It's also less confusing for people adding entries in the
documentation.

Signed-off-by: Olivier Matz <olivier.matz@6wind.com>
---
 doc/guides/rel_notes/release_16_07.rst | 86 +++++++++++++++++-----------------
 1 file changed, 43 insertions(+), 43 deletions(-)

diff --git a/doc/guides/rel_notes/release_16_07.rst b/doc/guides/rel_notes/release_16_07.rst
index f6d543c..71d3540 100644
--- a/doc/guides/rel_notes/release_16_07.rst
+++ b/doc/guides/rel_notes/release_16_07.rst
@@ -1,50 +1,50 @@
 DPDK Release 16.07
 ==================
 
-**Read this first.**
+.. **Read this first.**
 
-The text below explains how to update the release notes.
+   The text below explains how to update the release notes.
 
-Use proper spelling, capitalization and punctuation in all sections.
+   Use proper spelling, capitalization and punctuation in all sections.
 
-Variable and config names should be quoted as fixed width text: ``LIKE_THIS``.
+   Variable and config names should be quoted as fixed width text: ``LIKE_THIS``.
 
-Build the docs and view the output file to ensure the changes are correct::
+   Build the docs and view the output file to ensure the changes are correct::
 
-   make doc-guides-html
+      make doc-guides-html
 
-   firefox build/doc/html/guides/rel_notes/release_16_07.html
+      firefox build/doc/html/guides/rel_notes/release_16_07.html
 
 
 New Features
 ------------
 
-This section should contain new features added in this release. Sample format:
+.. This section should contain new features added in this release. Sample format:
 
-* **Add a title in the past tense with a full stop.**
+   * **Add a title in the past tense with a full stop.**
 
-  Add a short 1-2 sentence description in the past tense. The description
-  should be enough to allow someone scanning the release notes to understand
-  the new feature.
+     Add a short 1-2 sentence description in the past tense. The description
+     should be enough to allow someone scanning the release notes to understand
+     the new feature.
 
-  If the feature adds a lot of sub-features you can use a bullet list like this.
+     If the feature adds a lot of sub-features you can use a bullet list like this.
 
-  * Added feature foo to do something.
-  * Enhanced feature bar to do something else.
+     * Added feature foo to do something.
+     * Enhanced feature bar to do something else.
 
-  Refer to the previous release notes for examples.
+     Refer to the previous release notes for examples.
 
 
 Resolved Issues
 ---------------
 
-This section should contain bug fixes added to the relevant sections. Sample format:
+.. This section should contain bug fixes added to the relevant sections. Sample format:
 
-* **code/section Fixed issue in the past tense with a full stop.**
+   * **code/section Fixed issue in the past tense with a full stop.**
 
-  Add a short 1-2 sentence description of the resolved issue in the past tense.
-  The title should contain the code/lib section like a commit message.
-  Add the entries in alphabetic order in the relevant sections below.
+     Add a short 1-2 sentence description of the resolved issue in the past tense.
+     The title should contain the code/lib section like a commit message.
+     Add the entries in alphabetic order in the relevant sections below.
 
 
 EAL
@@ -77,21 +77,21 @@ Other
 Known Issues
 ------------
 
-This section should contain new known issues in this release. Sample format:
+.. This section should contain new known issues in this release. Sample format:
 
-* **Add title in present tense with full stop.**
+   * **Add title in present tense with full stop.**
 
-  Add a short 1-2 sentence description of the known issue in the present
-  tense. Add information on any known workarounds.
+     Add a short 1-2 sentence description of the known issue in the present
+     tense. Add information on any known workarounds.
 
 
 API Changes
 -----------
 
-This section should contain API changes. Sample format:
+.. This section should contain API changes. Sample format:
 
-* Add a short 1-2 sentence description of the API change. Use fixed width
-  quotes for ``rte_function_names`` or ``rte_struct_names``. Use the past tense.
+   * Add a short 1-2 sentence description of the API change. Use fixed width
+     quotes for ``rte_function_names`` or ``rte_struct_names``. Use the past tense.
 
 * The following counters are removed from ``rte_eth_stats`` structure:
   ibadcrc, ibadlen, imcasts, fdirmatch, fdirmiss,
@@ -101,9 +101,9 @@ This section should contain API changes. Sample format:
 ABI Changes
 -----------
 
-* Add a short 1-2 sentence description of the ABI change that was announced in
-  the previous releases and made in this release. Use fixed width quotes for
-  ``rte_function_names`` or ``rte_struct_names``. Use the past tense.
+.. * Add a short 1-2 sentence description of the ABI change that was announced in
+     the previous releases and made in this release. Use fixed width quotes for
+     ``rte_function_names`` or ``rte_struct_names``. Use the past tense.
 
 * The ``rte_port_source_params`` structure has new fields to support PCAP file.
   It was already in release 16.04 with ``RTE_NEXT_ABI`` flag.
@@ -112,7 +112,7 @@ ABI Changes
 Shared Library Versions
 -----------------------
 
-Update any library version updated in this release and prepend with a ``+`` sign.
+.. Update any library version updated in this release and prepend with a ``+`` sign.
 
 The libraries prepended with a plus sign were incremented in this version.
 
@@ -150,25 +150,25 @@ The libraries prepended with a plus sign were incremented in this version.
 Tested Platforms
 ----------------
 
-This section should contain a list of platforms that were tested with this
-release.
+.. This section should contain a list of platforms that were tested with this
+   release.
 
-The format is:
+   The format is:
 
-#. Platform name.
+   #. Platform name.
 
-   - Platform details.
-   - Platform details.
+      - Platform details.
+      - Platform details.
 
 
 Tested NICs
 -----------
 
-This section should contain a list of NICs that were tested with this release.
+.. This section should contain a list of NICs that were tested with this release.
 
-The format is:
+   The format is:
 
-#. NIC name.
+   #. NIC name.
 
-   - NIC details.
-   - NIC details.
+      - NIC details.
+      - NIC details.
-- 
2.8.0.rc3

Re: [dpdk-dev] [PATCH] doc: move rel_notes instructions as comments

[Mcnamara, John]

> -----Original Message-----
> From: Olivier Matz [mailto:olivier.matz@6wind.com]
> Sent: Friday, May 13, 2016 2:28 PM
> To: dev@dpdk.org
> Cc: Mcnamara, John <john.mcnamara@intel.com>
> Subject: [PATCH] doc: move rel_notes instructions as comments
> 
> We don't want to have this instructions in the generated docs, so use
> comments. It's also less confusing for people adding entries in the
> documentation.
> 
> Signed-off-by: Olivier Matz <olivier.matz@6wind.com>

Good idea.

Reviewed-by: John McNamara <john.mcnamara@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>

Re: [dpdk-dev] [PATCH] doc: move rel_notes instructions as comments

[Thomas Monjalon]

Hi John,

> Reviewed-by: John McNamara <john.mcnamara@intel.com>
> Acked-by: John McNamara <john.mcnamara@intel.com>

The meaning of Reviewed-by and Acked-by can be slightly different
but I don't think we need to put both.
In this case, as the doc maintainer, your ack should be fine.

By the way, I'm totally OK to discuss a better description of
these tags in the guidelines.

Re: [dpdk-dev] [PATCH] doc: move rel_notes instructions as comments

[Thomas Monjalon]

> > We don't want to have this instructions in the generated docs, so use
> > comments. It's also less confusing for people adding entries in the
> > documentation.
> > 
> > Signed-off-by: Olivier Matz <olivier.matz@6wind.com>
> 
> Good idea.
> 
> Reviewed-by: John McNamara <john.mcnamara@intel.com>
> Acked-by: John McNamara <john.mcnamara@intel.com>

Applied, thanks