[0/6] docs: Unify Getting Started Guides

  The separate Getting Started Guides for Linux, FreeBSD, and Windows have been 
consolidated into a single, streamlined guide to simplify the user experience 
and facilitate easier maintenance.

David Young (6):
  Section 1: Introduction
  Section 2: Install and Build DPDK
  Section 3: Setting up a System to Run DPDK Applications
  Section 4: Running Applications
  Section 5: Appendix
  Section 6: Glossary

 .../appendix/cross_compile_dpdk.rst           |  37 +++
 .../appendix/dpdk_meson_build_options.rst     |  57 ++++
 .../getting_started_guide/appendix/index.rst  |  17 +
 .../running_dpdk_apps_without_root.rst        |  36 +++
 .../appendix/vfio_advanced.rst                | 295 ++++++++++++++++++
 doc/guides/getting_started_guide/glossary.rst |  75 +++++
 .../building_from_sources.rst                 | 108 +++++++
 .../install_and_build/index.rst               |  15 +
 .../installing_prebuilt_packages.rst          |  54 ++++
 .../windows_install_build.rst                 |  93 ++++++
 doc/guides/getting_started_guide/intro.rst    |  16 +
 .../getting_started_guide/run_apps/index.rst  |  10 +
 .../run_apps/run_apps.rst                     | 118 +++++++
 .../getting_started_guide/system_setup.rst    | 195 ++++++++++++
 14 files changed, 1126 insertions(+)
 create mode 100644 doc/guides/getting_started_guide/appendix/cross_compile_dpdk.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/dpdk_meson_build_options.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/index.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/running_dpdk_apps_without_root.rst
 create mode 100644 doc/guides/getting_started_guide/appendix/vfio_advanced.rst
 create mode 100644 doc/guides/getting_started_guide/glossary.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/building_from_sources.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/index.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/installing_prebuilt_packages.rst
 create mode 100644 doc/guides/getting_started_guide/install_and_build/windows_install_build.rst
 create mode 100644 doc/guides/getting_started_guide/intro.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps/index.rst
 create mode 100644 doc/guides/getting_started_guide/run_apps/run_apps.rst
 create mode 100644 doc/guides/getting_started_guide/system_setup.rst
  

On Wed, Sep 20, 2023 at 11:48:04AM -0400, David Young wrote:
> The separate Getting Started Guides for Linux, FreeBSD, and Windows have been 
> consolidated into a single, streamlined guide to simplify the user experience 
> and facilitate easier maintenance.
> 

seems like a good idea to me. i'm assuming that the existing content is
just being re-organized. after the re-organization is complete i'll plan
to bring some of the windows specific content up to date.

thanks for doing this.

Series-acked-by: Tyler Retzlaff <roretzla@linux.microsoft.com>
  

Hello David,

On Wed, Sep 20, 2023 at 5:49 PM David Young <dave@youngcopy.com> wrote:
>
> The separate Getting Started Guides for Linux, FreeBSD, and Windows have been
> consolidated into a single, streamlined guide to simplify the user experience
> and facilitate easier maintenance.
>
> David Young (6):
>   Section 1: Introduction
>   Section 2: Install and Build DPDK
>   Section 3: Setting up a System to Run DPDK Applications
>   Section 4: Running Applications
>   Section 5: Appendix
>   Section 6: Glossary

From my understanding, existing copyright banners should be preserved
by this reorganisation work.
Yet I noticed a few Copyright banners dated 2025, please double check
and fix them.


Bruce, Thomas,
An open question, if new docs are created, who should this work be
attributed to? the dpdk contributors?


Thanks.
  

On Fri, Sep 22, 2023 at 04:47:55PM +0200, David Marchand wrote:
> Hello David,
> 
> On Wed, Sep 20, 2023 at 5:49 PM David Young <dave@youngcopy.com> wrote:
> >
> > The separate Getting Started Guides for Linux, FreeBSD, and Windows have been
> > consolidated into a single, streamlined guide to simplify the user experience
> > and facilitate easier maintenance.
> >
> > David Young (6):
> >   Section 1: Introduction
> >   Section 2: Install and Build DPDK
> >   Section 3: Setting up a System to Run DPDK Applications
> >   Section 4: Running Applications
> >   Section 5: Appendix
> >   Section 6: Glossary
> 
> From my understanding, existing copyright banners should be preserved
> by this reorganisation work.
> Yet I noticed a few Copyright banners dated 2025, please double check
> and fix them.
> 
> 
> Bruce, Thomas,
> An open question, if new docs are created, who should this work be
> attributed to? the dpdk contributors?
> 
For this re-organisation, I expect the copyrights from the existing content
be preserved - merging if so necessary, e.g. a page merged from two
separate ones with differen copyright owners.

For brand new content, the way things look now, it's just likely to come from
existing DPDK experts, so they will apply their usual attributions AFAIK.

/Bruce
  

On 9/20/2023 4:48 PM, David Young wrote:
> The separate Getting Started Guides for Linux, FreeBSD, and Windows have been 
> consolidated into a single, streamlined guide to simplify the user experience 
> and facilitate easier maintenance.
> 
> David Young (6):
>   Section 1: Introduction
>   Section 2: Install and Build DPDK
>   Section 3: Setting up a System to Run DPDK Applications
>   Section 4: Running Applications
>   Section 5: Appendix
>   Section 6: Glossary
> 

Hi David,

New documentations are not in the toctree, so they are not accessible by
the links in the left column.
Sphinx generates warning for this:
WARNING: document isn't included in any toctree

Also existing per platform documentation is not removed yet.

I assume both above done intentionally for the development phase of this
documentation, but this is just a reminder in-case not.


And not all context seems moved from existing per platform getting
started guides, is there are plan to keep them around for a while as
reference, or move that context to other files?


Thanks,
ferruh
  

Thank you for reviewing the patches and for your feedback.

1. Regarding the toctree, I've added the new Getting Started Guide so that
it's accessible via the links in the left column. I've tested this on my
local version, and the warning should disappear once the patch is submitted.

2. As for the existing per-platform documentation, it has not been removed
yet because I'm still in the process of developing the consolidated Getting
Started Guide. The existing documentation will remain in place for the time
being.

3. About the context not yet moved from the existing per-platform guides,
I'm considering how best to integrate this information into the new guide.
Bruce, do you have any thoughts on whether these should be kept around for
reference or moved to other files?

I plan to send updated versions of all patches in this series at the same
time, incorporating all the feedback received.

Thank you again for your time and input.

Thanks!
David Young
Professional Copywriter/Technical Writer
Young Copy
+1 (678) 500-9550
https://www.youngcopy.com


On Mon, Sep 25, 2023 at 7:54 AM Ferruh Yigit <ferruh.yigit@amd.com> wrote:

> On 9/20/2023 4:48 PM, David Young wrote:
> > The separate Getting Started Guides for Linux, FreeBSD, and Windows have
> been
> > consolidated into a single, streamlined guide to simplify the user
> experience
> > and facilitate easier maintenance.
> >
> > David Young (6):
> >   Section 1: Introduction
> >   Section 2: Install and Build DPDK
> >   Section 3: Setting up a System to Run DPDK Applications
> >   Section 4: Running Applications
> >   Section 5: Appendix
> >   Section 6: Glossary
> >
>
> Hi David,
>
> New documentations are not in the toctree, so they are not accessible by
> the links in the left column.
> Sphinx generates warning for this:
> WARNING: document isn't included in any toctree
>
> Also existing per platform documentation is not removed yet.
>
> I assume both above done intentionally for the development phase of this
> documentation, but this is just a reminder in-case not.
>
>
> And not all context seems moved from existing per platform getting
> started guides, is there are plan to keep them around for a while as
> reference, or move that context to other files?
>
>
> Thanks,
> ferruh
>
>
  

On Mon, Sep 25, 2023 at 12:54:15PM +0100, Ferruh Yigit wrote:
> On 9/20/2023 4:48 PM, David Young wrote:
> > The separate Getting Started Guides for Linux, FreeBSD, and Windows
> > have been consolidated into a single, streamlined guide to simplify the
> > user experience and facilitate easier maintenance.
> > 
> > David Young (6): Section 1: Introduction Section 2: Install and Build
> > DPDK Section 3: Setting up a System to Run DPDK Applications Section 4:
> > Running Applications Section 5: Appendix Section 6: Glossary
> > 
> 
> Hi David,
> 
> New documentations are not in the toctree, so they are not accessible by
> the links in the left column.  Sphinx generates warning for this:
> WARNING: document isn't included in any toctree
> 
> Also existing per platform documentation is not removed yet.
> 
> I assume both above done intentionally for the development phase of this
> documentation, but this is just a reminder in-case not.
> 
> 
> And not all context seems moved from existing per platform getting
> started guides, is there are plan to keep them around for a while as
> reference, or move that context to other files?
>
Part of the work in consolidating these docs is to remove any unnecessary
details. After all, these are Getting Started Guides, which should contain
only the minimal info for getting started and not much else. The more
content we have, the harder the docs become to follow. Some extra content
is moved to the appendicies, but I, for one, think we should keep these
docs as slim as possible. For example, we should document one way to do
things in the main doc. Any alternative methods should be documented via
links elsewhere.

For content that is not transferred over as part of this patchset, if there
are any concerns about omissions, I think we should discuss them on a case
by case basis. Just because something was in the original docs does not
mean it needs to go in the new one. :-)

/Bruce