Re: [dpdk-dev] [PATCH 2/3] doc: added guidelines on dpdk documentation

[Thomas Monjalon <thomas.monjalon@6wind.com>]

2015-07-02 14:50, John McNamara:
> Added guidelines on the purpose and structure of the DPDK
> documentation, how to build it and guidelines for creating it.
> 
> Also added guidelines on how to format and submit a documentation patch.

Good idea to have guidelines for doc.
But I think the submission guidelines shouldn't be specific to doc.
Could you move it to a contributing.rst file?
Guidelines from the website could be moved there.

> +  In general developers do not have to update the Release Notes apart from
> +  adding ABI announcements.

Someone must update the release notes.
Why not doing it atomicly when introducing a new feature?

> +  The guideline documents record the DPDK guidelines on coding, design, ABI
> +  usage and documentation.
> +
> +  These should be changed to clarify or improve guidelines.

The guideline documents record community process, expectations and design
directions.

They can be extended, amended or discussed by submitting a patch and getting
community approval.

> +* Sphinx.

Sphinx (also called python-sphinx).

> +
> +* TexLive.

TexLive (at least TexLive-core, extra Latex support and extra fonts). 

> +   # Ubuntu/Debian.
> +
> +   sudo apt-get -y install texlive-full

lighter:
sudo apt-get -y install texlive-latex-extra texlive-fonts-extra texlive-fonts-recommended

> +   # Red Hat/Fedora, selective install.
> +   sudo yum -y install texlive
> +   sudo yum -y install texlive-latex
> +   sudo yum -y install texlive-collection-latex
> +   sudo yum -y install texlive-collection-latexrecommended
> +   sudo yum -y install texlive-collection-latexextra
> +   sudo yum -y install texlive-dejavu

simpler:
sudo yum -y install texlive-collection-latexextra, texlive-collection-fontsextra

> +       aspell --lang=en_US --check doc/guides/sample_app_ug/mydoc.rst

Good tip!
What about making it more visible? :)

> +* Use one sentence per line in a paragraph, i.e., put a newline character
> +  after each period/full stop.

What about adding this?
Only blank line will generate a newline.

I think breaking lines at end of sentence is more important than
wrapping at 80 char, because it will help to keep patches
readable.

> +* Use one line per paragraph.

Why this recommendation? I think it doesn't help.

> +* Avoid lines longer than 80 character in literal blocks since they can exceed
> +  the page width when converted to PDF documentation. If possible try to wrap
> +  the text at sensible locations. For example a long command line could be
> +  documented like this and still work if copied directly from the docs::
> +
> +     build/app/testpmd -c7 -n3 --vdev=eth_pcap0,iface=eth0     \
> +                               --vdev=eth_pcap1,iface=eth1     \
> +                               -- -i --nb-cores=2 --nb-ports=2 \
> +                                  --total-num-mbufs=2048

Yes. Maybe that "avoid" is not strong enough.

> +* RST tables should be used sparingly. They are hard to format and to edit,
> +  they are often rendered incorrectly in PDF format, and the same information
> +  can usually be shown just as clearly with a list.

... or with a definition list.

> +* The use of a label is preferred since it works across files and will still
> +  work if the header text changes.

Artificial labels are a bit ugly.
If a header change, there will be an error for the link, right?

> +Doxygen Guidelines
> +------------------

I think you should split your patch here and have a separate patch to move
the doxygen guidelines from the coding style doc.

> +Patching the Documentation
> +--------------------------
> +
> +One of the easiest ways to contribute to DPDK is to submit a patch to the
> +documentation.
> +
> +Over time the documentation may contain information that is slightly out of
> +date or that could be improved upon. Newcomers to the DPDK project often
> +notice these issues as they work through the examples and how-to guides.
> +
> +Rather than emailing the development list, or even ignoring the issue, it is
> +just as easy to submit a patch to fix it. The following instructions explain
> +how to do that and since they are meant to encourage contributions they assume
> +no development experience or prior exposure to the DPDK workflow.
> +
> +#. Install the documentation dependencies as shown above. As a minimum you
> +   should install Sphinx::
> +

Using a link to above section would ease future update or extension.

> +      # Ubuntu/Debian.
> +      sudo apt-get -y install python-sphinx
> +
> +      # Red Hat/Fedora.
> +      sudo yum     -y install python-sphinx
> +
> +   If you are going to patch the API docs you will need Doxygen. You can omit
> +   TexLive and Inkscape for now.
> +

>From this point, it could be a link to a starter section in a contributing doc.

> +#. Install ``git`` as follows::
[...]
> +#. Clone the DPDK repository (this can take a minute or two)::
[...]

>From this point, it is specific to doc.

> +      make doc-guides-html
> +
> +   If you get warnings about missing utilities go back and work through
> +   installing the dependencies again.
[...]
> +      You can ignore a warning about upgrading Sphinx, that is optional. If
> +      you are building the documentation on Mac OS you can ignore a warning
> +      from ``sed``.

Not aware of this warning. Could it be removed?

> +#. If everything is okay you can commit your changes to your local repository
> +   and generate a patch. The first step is to add the file(s) that you
> +   modified::
> +
> +      git add doc/guides/linux_gsg/quick_start.rst
> +
> +#. Now commit the changes to the local repository. You must "sign" the commit
> +   by using ``-s``. This will insert the name and email address that you
> +   configured in your ``.gitconfig`` above::
> +
> +      git commit -s

For a primer doc, "git commit -as" skip the "git add" step and would be OK.

> +      doc: fix minor typo in linux getting started guide
> +
> +      Fixed a minor typo in the Linux Getting Started Guide.

No need to repeat the title.
It would be more interesting to know why it is better after the patch.
In case of a typo, no comment is needed after the title.

>From this point, it is not specific to doc.