Previous DPDK version API documentation for app developers

Previous DPDK version API documentation for app developers

[Matthew Hall]

Hi all,

I ran into a funny situation today with the API documentation.

For stability until I can get my app mostly working, I was using DPDK 1.7.X, 
so I could concentrate on making the app reliable. But the DPDK website only 
has the API docs for DPDK 1.8.X / HEAD.

I was wondering if we could have copies of the most recent few versions in the 
site, and some scripts or steps to regenerate locally so you can get the 
matching version in the local machine.

This would also help me to do some suppoert things for our community, like 
making small patches to fix parts of the docs with typos / formatting bugs. 

With the steps how to generate them right, I could fix docs bugs in the 
sources and make sure the docs read right afterward for others.

Thanks,
Matthew.

Re: Previous DPDK version API documentation for app developers

[Panu Matilainen]

On 02/12/2015 09:06 AM, Matthew Hall wrote:
> Hi all,
>
> I ran into a funny situation today with the API documentation.
>
> For stability until I can get my app mostly working, I was using DPDK 1.7.X,
> so I could concentrate on making the app reliable. But the DPDK website only
> has the API docs for DPDK 1.8.X / HEAD.
>
> I was wondering if we could have copies of the most recent few versions in the
> site, and some scripts or steps to regenerate locally so you can get the
> matching version in the local machine.

Same goes for release notes: old versions should be kept around and 
preferably at the original url, which requires them to be versioned from 
the start.

	- Panu -

Re: Previous DPDK version API documentation for app developers

[Thomas Monjalon]

2015-02-12 11:03, Panu Matilainen:
> On 02/12/2015 09:06 AM, Matthew Hall wrote:
> > Hi all,
> >
> > I ran into a funny situation today with the API documentation.
> >
> > For stability until I can get my app mostly working, I was using DPDK 1.7.X,
> > so I could concentrate on making the app reliable. But the DPDK website only
> > has the API docs for DPDK 1.8.X / HEAD.
> >
> > I was wondering if we could have copies of the most recent few versions in the
> > site, and some scripts or steps to regenerate locally so you can get the
> > matching version in the local machine.
> 
> Same goes for release notes: old versions should be kept around and 
> preferably at the original url, which requires them to be versioned from 
> the start.

Panu, release notes are part of the git tree since release 1.8.

Re: Previous DPDK version API documentation for app developers

[Panu Matilainen]

On 02/12/2015 11:39 AM, Thomas Monjalon wrote:
> 2015-02-12 11:03, Panu Matilainen:
>> On 02/12/2015 09:06 AM, Matthew Hall wrote:
>>> Hi all,
>>>
>>> I ran into a funny situation today with the API documentation.
>>>
>>> For stability until I can get my app mostly working, I was using DPDK 1.7.X,
>>> so I could concentrate on making the app reliable. But the DPDK website only
>>> has the API docs for DPDK 1.8.X / HEAD.
>>>
>>> I was wondering if we could have copies of the most recent few versions in the
>>> site, and some scripts or steps to regenerate locally so you can get the
>>> matching version in the local machine.
>>
>> Same goes for release notes: old versions should be kept around and
>> preferably at the original url, which requires them to be versioned from
>> the start.
>
> Panu, release notes are part of the git tree since release 1.8.
>

Sure, but what you find at 
http://dpdk.org/browse/dpdk/tree/doc/guides/rel_notes?h=releases&id=v1.8.0 
is not very presentable, even if it is readable in the "source" format.

What I mean is ... oh, http://dpdk.org/doc/guides-1.8/ works so it IS 
already there, only entirely hidden in the sense that nothing at all 
points to the versioned tree AFAICS.

So never mind then :) except perhaps making the versioned docs (API and 
all) more visible.

	- Panu -

Re: Previous DPDK version API documentation for app developers

[Thomas Monjalon]

Hi Matthew,

2015-02-11 23:06, Matthew Hall:
> Hi all,
> 
> I ran into a funny situation today with the API documentation.
> 
> For stability until I can get my app mostly working, I was using DPDK 1.7.X, 
> so I could concentrate on making the app reliable. But the DPDK website only 
> has the API docs for DPDK 1.8.X / HEAD.

Yes, previous policy was to publish only the doc of latest release.
But starting with 1.8 (first release including guides), we'll keep every versions.
Example:
	http://dpdk.org/doc/api
	http://dpdk.org/doc/api-1.8
The web page will be modified to list different versions.

> I was wondering if we could have copies of the most recent few versions in the 
> site, and some scripts or steps to regenerate locally so you can get the 
> matching version in the local machine.

Yes you can: make doc
For doxygen API only: make doc-api-html
For sphinx only: doc-guides-html.

> This would also help me to do some suppoert things for our community, like 
> making small patches to fix parts of the docs with typos / formatting bugs. 
> 
> With the steps how to generate them right, I could fix docs bugs in the 
> sources and make sure the docs read right afterward for others.

Thanks

Re: Previous DPDK version API documentation for app developers

[Matthew Hall]

On Feb 12, 2015, at 1:29 AM, Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org> wrote:
> Yes you can: make doc
> For doxygen API only: make doc-api-html
> For sphinx only: doc-guides-html.

Hi Thomas,

In 1.7 for me at least I found the target was called: doc-htmlapi .

Did the way this stuff works get changed at some point?

Thanks,
Matthew.

Re: Previous DPDK version API documentation for app developers

[Thomas Monjalon]

2015-02-17 00:48, Matthew Hall:
> On Feb 12, 2015, at 1:29 AM, Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org> wrote:
> > Yes you can: make doc
> > For doxygen API only: make doc-api-html
> > For sphinx only: doc-guides-html.
> 
> Hi Thomas,
> 
> In 1.7 for me at least I found the target was called: doc-htmlapi .
> 
> Did the way this stuff works get changed at some point?

Yes, you're right. It has been renamed.
But I think you should better work on improving the HEAD ;)

Re: Previous DPDK version API documentation for app developers

[Matthew Hall]

On Feb 17, 2015, at 1:30 AM, Thomas Monjalon <thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org> wrote:
> Yes, you're right. It has been renamed.
> But I think you should better work on improving the HEAD ;)

Yes, I agree. But to get to this point I have to get the core application features to even work in 1.7, before I can switch the app to 1.8. :)

It should not be too much longer I hope. I'm pushing hard on the last feature I want done, but it's server-side-only TCP so it will take a while I think.

Matthew.