| Message ID | 1437675306-16381-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | New |
| Headers | show |
Mike, I'm looking to generated html docs and it looks like it's better to put that pages under User guide section. Best regards, Maxim. On 07/23/15 21:15, Mike Holmes wrote: > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > doc/doxygen.cfg | 2 +- > doc/odp.dox | 9 +++++++++ > 2 files changed, 10 insertions(+), 1 deletion(-) > > diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg > index 213a903..f28ec24 100644 > --- a/doc/doxygen.cfg > +++ b/doc/doxygen.cfg > @@ -28,7 +28,7 @@ CLASS_DIAGRAMS = NO > HAVE_DOT = YES > CALL_GRAPH = YES > DOT_MULTI_TARGETS = NO > -EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform > +EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform $(SRCDIR) > EXAMPLE_PATTERNS = *.c > EXAMPLE_RECURSIVE = YES > IMAGE_PATH = $(SRCDIR)/doc/images > diff --git a/doc/odp.dox b/doc/odp.dox > index 0a3bc73..d031f85 100644 > --- a/doc/odp.dox > +++ b/doc/odp.dox > @@ -41,3 +41,12 @@ > * - Bug tracking is https://bugs.linaro.org/buglist.cgi?product=OpenDataPlane > * > */ > + > +/**@page contributing Contributing Guide Lines > + * @verbinclude CONTRIBUTING > + */ > + > +/**@page dependencies Dependencies Build Guide > + * @verbinclude DEPENDENCIES > + */ > +
On 29 July 2015 at 07:51, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: > Mike, I'm looking to generated html docs and it looks like it's better to > put that pages under User guide section. > There are two levels of information, the basic requirements and a human walk though. The contributing and dependencies from the src are the bare minimum information. They are part of the API SRC code. I think placing them is the API DOC follows the theme of doxygen that the api doc is the "pretty" rendering of the same information you can get by reading the header and makefiles directly - all low level and factual and generated from the src. This information should be a similar level to http://dpdk.org/doc/quick-start The users guide is different, it is a verbose human document about the API and not just the terse requirements to build it. In this doc we should talk about how to use the API and building it should be described at length as part of that. This information should be similar in level to http://dpdk.org/doc/guides/linux_gsg/index.html and http://dpdk.org/doc/guides/prog_guide/index.html > Best regards, > Maxim. > > > On 07/23/15 21:15, Mike Holmes wrote: > >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> doc/doxygen.cfg | 2 +- >> doc/odp.dox | 9 +++++++++ >> 2 files changed, 10 insertions(+), 1 deletion(-) >> >> diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg >> index 213a903..f28ec24 100644 >> --- a/doc/doxygen.cfg >> +++ b/doc/doxygen.cfg >> @@ -28,7 +28,7 @@ CLASS_DIAGRAMS = NO >> HAVE_DOT = YES >> CALL_GRAPH = YES >> DOT_MULTI_TARGETS = NO >> -EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform >> +EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform $(SRCDIR) >> EXAMPLE_PATTERNS = *.c >> EXAMPLE_RECURSIVE = YES >> IMAGE_PATH = $(SRCDIR)/doc/images >> diff --git a/doc/odp.dox b/doc/odp.dox >> index 0a3bc73..d031f85 100644 >> --- a/doc/odp.dox >> +++ b/doc/odp.dox >> @@ -41,3 +41,12 @@ >> * - Bug tracking is >> https://bugs.linaro.org/buglist.cgi?product=OpenDataPlane >> * >> */ >> + >> +/**@page contributing Contributing Guide Lines >> + * @verbinclude CONTRIBUTING >> + */ >> + >> +/**@page dependencies Dependencies Build Guide >> + * @verbinclude DEPENDENCIES >> + */ >> + >> > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
On 07/29/15 15:22, Mike Holmes wrote: > > > On 29 July 2015 at 07:51, Maxim Uvarov <maxim.uvarov@linaro.org > <mailto:maxim.uvarov@linaro.org>> wrote: > > Mike, I'm looking to generated html docs and it looks like it's > better to put that pages under User guide section. > > > There are two levels of information, the basic requirements and a > human walk though. > The contributing and dependencies from the src are the bare minimum > information. They are part of the API SRC code. I think placing them > is the API DOC follows the theme of doxygen that the api doc is the > "pretty" rendering of the same information you can get by reading the > header and makefiles directly - all low level and factual and > generated from the src. > This information should be a similar level to > http://dpdk.org/doc/quick-start I'm not sure that dependencies are part of API. It's dependencies to compile linux-generic platform which in the same repo as API definitions (api header files). That information can be interesting for users who want to compile linux-generic and try it and useless for people who look only on API. That is why I think it's more fit to UG for linux-generic platform then to common API. Maxim. > > The users guide is different, it is a verbose human document about the > API and not just the terse requirements to build it. In this doc we > should talk about how to use the API and building it should be > described at length as part of that. > This information should be similar in level to > http://dpdk.org/doc/guides/linux_gsg/index.html and > http://dpdk.org/doc/guides/prog_guide/index.html > > > > Best regards, > Maxim. > > > On 07/23/15 21:15, Mike Holmes wrote: > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org > <mailto:mike.holmes@linaro.org>> > --- > doc/doxygen.cfg | 2 +- > doc/odp.dox | 9 +++++++++ > 2 files changed, 10 insertions(+), 1 deletion(-) > > diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg > index 213a903..f28ec24 100644 > --- a/doc/doxygen.cfg > +++ b/doc/doxygen.cfg > @@ -28,7 +28,7 @@ CLASS_DIAGRAMS = NO > HAVE_DOT = YES > CALL_GRAPH = YES > DOT_MULTI_TARGETS = NO > -EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform > +EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform $(SRCDIR) > EXAMPLE_PATTERNS = *.c > EXAMPLE_RECURSIVE = YES > IMAGE_PATH = $(SRCDIR)/doc/images > diff --git a/doc/odp.dox b/doc/odp.dox > index 0a3bc73..d031f85 100644 > --- a/doc/odp.dox > +++ b/doc/odp.dox > @@ -41,3 +41,12 @@ > * - Bug tracking is > https://bugs.linaro.org/buglist.cgi?product=OpenDataPlane > * > */ > + > +/**@page contributing Contributing Guide Lines > + * @verbinclude CONTRIBUTING > + */ > + > +/**@page dependencies Dependencies Build Guide > + * @verbinclude DEPENDENCIES > + */ > + > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> > https://lists.linaro.org/mailman/listinfo/lng-odp > > > > > -- > Mike Holmes > Technical Manager - Linaro Networking Group > Linaro.org <http://www.linaro.org/>***│ *Open source software for ARM SoCs >
On 29 July 2015 at 08:52, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: > On 07/29/15 15:22, Mike Holmes wrote: > >> >> >> On 29 July 2015 at 07:51, Maxim Uvarov <maxim.uvarov@linaro.org <mailto: >> maxim.uvarov@linaro.org>> wrote: >> >> Mike, I'm looking to generated html docs and it looks like it's >> better to put that pages under User guide section. >> >> >> There are two levels of information, the basic requirements and a human >> walk though. >> The contributing and dependencies from the src are the bare minimum >> information. They are part of the API SRC code. I think placing them is the >> API DOC follows the theme of doxygen that the api doc is the "pretty" >> rendering of the same information you can get by reading the header and >> makefiles directly - all low level and factual and generated from the src. >> This information should be a similar level to >> http://dpdk.org/doc/quick-start >> > > I'm not sure that dependencies are part of API. It's dependencies to > compile linux-generic platform which in the same repo as API definitions > (api header files). That information can be interesting for users who want > to compile linux-generic and try it and useless for people who look only on > API. That is why I think it's more fit to UG for linux-generic platform > then to common API. > That is a good point, but we still bundle the API with linux-generic as the non-performance reference so the information in the API guide is the information from linux-generic. Do we agree to add contributing, and bump dependencies to the user guide - I am fine with that if we continue to separate linux-generic from the API, a direction supported by the current config.h work. > > Maxim. > > >> The users guide is different, it is a verbose human document about the >> API and not just the terse requirements to build it. In this doc we should >> talk about how to use the API and building it should be described at length >> as part of that. >> This information should be similar in level to >> http://dpdk.org/doc/guides/linux_gsg/index.html and >> http://dpdk.org/doc/guides/prog_guide/index.html >> >> >> >> Best regards, >> Maxim. >> >> >> On 07/23/15 21:15, Mike Holmes wrote: >> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org >> <mailto:mike.holmes@linaro.org>> >> >> --- >> doc/doxygen.cfg | 2 +- >> doc/odp.dox | 9 +++++++++ >> 2 files changed, 10 insertions(+), 1 deletion(-) >> >> diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg >> index 213a903..f28ec24 100644 >> --- a/doc/doxygen.cfg >> +++ b/doc/doxygen.cfg >> @@ -28,7 +28,7 @@ CLASS_DIAGRAMS = NO >> HAVE_DOT = YES >> CALL_GRAPH = YES >> DOT_MULTI_TARGETS = NO >> -EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform >> +EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform $(SRCDIR) >> EXAMPLE_PATTERNS = *.c >> EXAMPLE_RECURSIVE = YES >> IMAGE_PATH = $(SRCDIR)/doc/images >> diff --git a/doc/odp.dox b/doc/odp.dox >> index 0a3bc73..d031f85 100644 >> --- a/doc/odp.dox >> +++ b/doc/odp.dox >> @@ -41,3 +41,12 @@ >> * - Bug tracking is >> https://bugs.linaro.org/buglist.cgi?product=OpenDataPlane >> * >> */ >> + >> +/**@page contributing Contributing Guide Lines >> + * @verbinclude CONTRIBUTING >> + */ >> + >> +/**@page dependencies Dependencies Build Guide >> + * @verbinclude DEPENDENCIES >> + */ >> + >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org> >> https://lists.linaro.org/mailman/listinfo/lng-odp >> >> >> >> >> -- >> Mike Holmes >> Technical Manager - Linaro Networking Group >> Linaro.org <http://www.linaro.org/>***│ *Open source software for ARM >> SoCs >> >> >
diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index 213a903..f28ec24 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -28,7 +28,7 @@ CLASS_DIAGRAMS = NO HAVE_DOT = YES CALL_GRAPH = YES DOT_MULTI_TARGETS = NO -EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform +EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/platform $(SRCDIR) EXAMPLE_PATTERNS = *.c EXAMPLE_RECURSIVE = YES IMAGE_PATH = $(SRCDIR)/doc/images diff --git a/doc/odp.dox b/doc/odp.dox index 0a3bc73..d031f85 100644 --- a/doc/odp.dox +++ b/doc/odp.dox @@ -41,3 +41,12 @@ * - Bug tracking is https://bugs.linaro.org/buglist.cgi?product=OpenDataPlane * */ + +/**@page contributing Contributing Guide Lines + * @verbinclude CONTRIBUTING + */ + +/**@page dependencies Dependencies Build Guide + * @verbinclude DEPENDENCIES + */ +
Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- doc/doxygen.cfg | 2 +- doc/odp.dox | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-)