[dpdk-dev] Warnings when building the doc on Ubuntu 18.04

[dpdk-dev] Warnings when building the doc on Ubuntu 18.04

[David Marchand]

Hello,

I tried to build the documentation but it looks like the instructions
about how to build it are not up to date. Currently running Ubuntu
18.04, it might be the reason.

marchand@gribouille:~/git/dpdk$ make doc
[...]
lookup cache used 16122/65536 hits=132815 misses=16618
finished...
sphinx processing guides-html...
sphinx processing guides-pdf-faq...
/home/marchand/git/dpdk/doc/guides/faq/faq.rst:7: WARNING: undefined
label: linux_gsg (if the link has no caption the label must precede a
section header)
/home/marchand/git/dpdk/doc/guides/faq/faq.rst:25: WARNING: undefined
label: linux_gsg (if the link has no caption the label must precede a
section header)
/home/marchand/git/dpdk/doc/guides/faq/faq.rst:190: WARNING: undefined
label: multi_process_app (if the link has no caption the label must
precede a section header)
pdflatex processing guides-pdf-faq...
make[2]: latexmk: Command not found
Makefile:33: recipe for target 'doc.pdf' failed
make[2]: *** [doc.pdf] Error 127
/home/marchand/git/dpdk/mk/rte.sdkdoc.mk:81: recipe for target
'guides-pdf-faq' failed
make[1]: *** [guides-pdf-faq] Error 2
/home/marchand/git/dpdk/mk/rte.sdkroot.mk:88: recipe for target 'doc-all' failed
make: *** [doc-all] Error 2

So I installed the latexmk package.
Nothing in the dpdk refers to it, so it might be an external issue.


After this, I still see those warnings (and actually a lot of others).
The pdf generated docs have no link in them, but the html ones are fine.
Is is expected ?


-- 
David Marchand

Re: [dpdk-dev] Warnings when building the doc on Ubuntu 18.04

[Thomas Monjalon]

17/09/2018 11:59, David Marchand:
> Hello,
> 
> I tried to build the documentation but it looks like the instructions
> about how to build it are not up to date. Currently running Ubuntu
> 18.04, it might be the reason.

In pkg/dpdk.spec, there is this requirement (for RedHat based distro):
	doxygen, python-sphinx, inkscape, texlive-collection-latexextra
I am not sure it is up to date though.

There is also a guide listing the dependencies:
	doc/guides/contributing/documentation.rst
Here, it is mentioned
	TexLive (at least TexLive-core and the extra Latex support)
and
	# Ubuntu/Debian.
	sudo apt-get -y install texlive-latex-extra

Is it enough? Or is there a miss?

[...]
> So I installed the latexmk package.
> Nothing in the dpdk refers to it, so it might be an external issue.

Is latexmk a dependency of texlive-latex-extra?

> After this, I still see those warnings (and actually a lot of others).
> The pdf generated docs have no link in them, but the html ones are fine.
> Is is expected ?

The warnings are about the cross-doc links.
I think links are working inside a PDF but obviously not when referencing
another PDF document.
Do you see a different issue?

Re: [dpdk-dev] Warnings when building the doc on Ubuntu 18.04

[David Marchand]

On Mon, Sep 17, 2018 at 12:15 PM, Thomas Monjalon <thomas@monjalon.net> wrote:
> 17/09/2018 11:59, David Marchand:
>> Hello,
>>
>> I tried to build the documentation but it looks like the instructions
>> about how to build it are not up to date. Currently running Ubuntu
>> 18.04, it might be the reason.
>
> In pkg/dpdk.spec, there is this requirement (for RedHat based distro):
>         doxygen, python-sphinx, inkscape, texlive-collection-latexextra
> I am not sure it is up to date though.
>
> There is also a guide listing the dependencies:
>         doc/guides/contributing/documentation.rst
> Here, it is mentioned
>         TexLive (at least TexLive-core and the extra Latex support)
> and
>         # Ubuntu/Debian.
>         sudo apt-get -y install texlive-latex-extra

I followed this doc, yes.

> Is it enough? Or is there a miss?

I am more under the impression that there is a pb.

# on a fresh Ubuntu 16.04,

root@ubuntu1604:~# apt-cache rdepends latexmk
latexmk
Reverse Depends:
  latexila
  texlive-full
  texlive-full
  texlive-extra-utils

# and on my ubuntu 18.04
marchand@gribouille:~$ apt-cache rdepends latexmk
latexmk
Reverse Depends:
  latexila
  texlive-full
  texlive-extra-utils
  python-sphinx
  python3-sphinx
  jupyter-sphinx-theme-doc

texlive-latex-extra does not depend on latexmk.
So 16.04 vs 18.04 is not the issue.


Looking again at 16.04 :

root@ubuntu1604:~# apt-cache depends latexila |grep latexmk
  Recommends: latexmk
root@ubuntu1604:~# apt-cache depends texlive-full |grep latexmk
  Depends: latexmk
root@ubuntu1604:~# apt-cache depends texlive-extra-utils |grep latexmk
  Suggests: latexmk

So texlive-full is the only that has a hard dependency on it.


>> After this, I still see those warnings (and actually a lot of others).
>> The pdf generated docs have no link in them, but the html ones are fine.
>> Is is expected ?
>
> The warnings are about the cross-doc links.
> I think links are working inside a PDF but obviously not when referencing
> another PDF document.
> Do you see a different issue?

Two types of warnings, "unknown label" and "unknown document".

The "unknown label" warnings seem to be cross doc links, yes.
But some unknown document warnings are odd to me.
I will look at this a bit more.


-- 
David Marchand

Re: [dpdk-dev] Warnings when building the doc on Ubuntu 18.04

[David Marchand]

On Mon, Sep 17, 2018 at 1:34 PM, David Marchand
<david.marchand@6wind.com> wrote:
> On Mon, Sep 17, 2018 at 12:15 PM, Thomas Monjalon <thomas@monjalon.net> wrote:
>> 17/09/2018 11:59, David Marchand:
>>> After this, I still see those warnings (and actually a lot of others).
>>> The pdf generated docs have no link in them, but the html ones are fine.
>>> Is is expected ?
>>
>> The warnings are about the cross-doc links.
>> I think links are working inside a PDF but obviously not when referencing
>> another PDF document.
>> Do you see a different issue?
>
> Two types of warnings, "unknown label" and "unknown document".
>
> The "unknown label" warnings seem to be cross doc links, yes.
> But some unknown document warnings are odd to me.
> I will look at this a bit more.

In the end, nothing special.
Just references to other docs or cross doc links.


-- 
David Marchand