making documentation targets on v4.10 with Fedora 25

making documentation targets on v4.10 with Fedora 25

[Jim Davis]

I ran a script like the one below to make the various Sphinx and
DocBook documentations targets for v4.10 on my Fedora 25 desktop

make O=/tmp/sphinx-out DOCBOOKS="" htmldocs
make O=/tmp/sphinx-out DOCBOOKS="" latexdocs
make O=/tmp/sphinx-out DOCBOOKS="" pdfdocs
make O=/tmp/sphinx-out DOCBOOKS="" epubdocs
make O=/tmp/sphinx-out DOCBOOKS="" xmldocs
make O=/tmp/sphinx-out DOCBOOKS="" cleandocs

make O=/tmp/docbook-out SPHINXBUILD=/none/such htmldocs
make O=/tmp/docbook-out SPHINXBUILD=/none/such pdfdocs
make O=/tmp/docbook-out SPHINXBUILD=/none/such psdocs
make O=/tmp/docbook-out SPHINXBUILD=/none/such xmldocs
make O=/tmp/docbook-out SPHINXBUILD=/none/such mandocs
make O=/tmp/docbook-out SPHINXBUILD=/none/such installmandocs
make O=/tmp/docbook-out SPHINXBUILD=/none/such cleandocs

with mixed results.

For the Sphinx targets, htmldocs, pdfdocs, epubdocs, and cleandocs
failed.  cleandocs works without the O= argument, and arguably the O=
thing isn't very useful with any of these targets, but it is supported
by the top-level Makefile.

For the DocBook targets, pdfdocs and psdocs failed.

pdfdocs (Sphinx or DocBook) has been broken for some time, while
psdocs hasn't worked in ages.  The errors with the Sphinx htmldocs and
epubdocs targets seem to be some Python issue:

Exception occurred:
  File "/usr/lib/python3.5/site-packages/docutils/writers/_html_base.py", line
671, in depart_document
    assert not self.context, 'len(context) = %s' % len(self.context)
AssertionError: len(context) = 1
The full traceback has been saved in /tmp/sphinx-err-o52yw6s4.log, if you want
to report the issue to the developers.
Please also report this if it was a user error, so that a better error message
can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphi
nx/issues>. Thanks!
make[2]: *** [epubdocs] Error 1
make[1]: *** [epubdocs] Error 2
make: *** [sub-make] Error 2

and similarly for htmldocs.

-- 
Jim

Re: making documentation targets on v4.10 with Fedora 25

[Jonathan Corbet]

On Mon, 20 Feb 2017 12:19:24 -0700
Jim Davis <jim.epost@gmail.com> wrote:

> pdfdocs (Sphinx or DocBook) has been broken for some time, while
> psdocs hasn't worked in ages.  The errors with the Sphinx htmldocs and
> epubdocs targets seem to be some Python issue:

pdfdocs works for me.  With Fedora, there are a thousand little TeX
packages that have to be installed before things go right.  I know...we
should, like, document those or something...on my list...

> Exception occurred:
>   File "/usr/lib/python3.5/site-packages/docutils/writers/_html_base.py", line
> 671, in depart_document
>     assert not self.context, 'len(context) = %s' % len(self.context)
> AssertionError: len(context) = 1

I've just started getting that kind of stuff on the F25 box.  Some recent
update clearly broke things; not fun.

Thanks,

jon

Re: making documentation targets on v4.10 with Fedora 25

[Jim Davis]

On Mon, Feb 20, 2017 at 4:20 PM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Mon, 20 Feb 2017 12:19:24 -0700
> Jim Davis <jim.epost@gmail.com> wrote:
>
>> pdfdocs (Sphinx or DocBook) has been broken for some time, while
>> psdocs hasn't worked in ages.  The errors with the Sphinx htmldocs and
>> epubdocs targets seem to be some Python issue:
>
> pdfdocs works for me.  With Fedora, there are a thousand little TeX
> packages that have to be installed before things go right.

Installing texlive-scheme-full -- which in turn installed 3,153 (!)
packages -- still didn't get make pdfdocs working on my Fedora 25
desktop... same failure with user.pdf that I posted about previously.
No joy with make psdocs either, but it's a PDF world now (and there's
always pdf2ps) so perhaps that target should disappear.

-- 
Jim

Re: making documentation targets on v4.10 with Fedora 25

[Jani Nikula]

On Mon, 20 Feb 2017, Jim Davis <jim.epost@gmail.com> wrote:
> For the Sphinx targets, htmldocs, pdfdocs, epubdocs, and cleandocs
> failed.  cleandocs works without the O= argument, and arguably the O=
> thing isn't very useful with any of these targets, but it is supported
> by the top-level Makefile.

Why do you say O= isn't useful with the targets? The goal was that it
would work as expected, and it did work in the past. But, as with
everything, if there's no automated testing, it ceases to exist. :(

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center

Re: making documentation targets on v4.10 with Fedora 25

[Jim Davis]

On Thu, Feb 23, 2017 at 2:59 AM, Jani Nikula
<jani.nikula@linux.intel.com> wrote:
> On Mon, 20 Feb 2017, Jim Davis <jim.epost@gmail.com> wrote:
>> For the Sphinx targets, htmldocs, pdfdocs, epubdocs, and cleandocs
>> failed.  cleandocs works without the O= argument, and arguably the O=
>> thing isn't very useful with any of these targets, but it is supported
>> by the top-level Makefile.
>
> Why do you say O= isn't useful with the targets?

You're right, they are.  Silly me.

Something like

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index 707c65337ebf..eb4294322150 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -98,7 +98,7 @@ installmandocs:

 cleandocs:
        $(Q)rm -rf $(BUILDDIR)
-       $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media clean
+       $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C
$(srctree)/Documentation/media clean

 endif # HAVE_SPHINX

seems to get cleandocs working again.


-- 
Jim

Re: making documentation targets on v4.10 with Fedora 25

[Markus Heiser]

On 23.02.2017 20:44, Jim Davis wrote:
> On Thu, Feb 23, 2017 at 2:59 AM, Jani Nikula
> <jani.nikula@linux.intel.com> wrote:
>> On Mon, 20 Feb 2017, Jim Davis <jim.epost@gmail.com> wrote:
>>> For the Sphinx targets, htmldocs, pdfdocs, epubdocs, and cleandocs
>>> failed.  cleandocs works without the O= argument, and arguably the O=
>>> thing isn't very useful with any of these targets, but it is supported
>>> by the top-level Makefile.
>>
>> Why do you say O= isn't useful with the targets?
>
> You're right, they are.  Silly me.
>
> Something like
>
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index 707c65337ebf..eb4294322150 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -98,7 +98,7 @@ installmandocs:
>
>  cleandocs:
>         $(Q)rm -rf $(BUILDDIR)
> -       $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media clean
> +       $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C
> $(srctree)/Documentation/media clean
>
>  endif # HAVE_SPHINX
>
> seems to get cleandocs working again.

I guess the O= error was already patched:

   http://www.spinics.net/lists/linux-doc/msg42989.html


-- Markus --

>
>

Re: making documentation targets on v4.10 with Fedora 25

[Jim Davis]

On Mon, Feb 20, 2017 at 4:20 PM, Jonathan Corbet <corbet@lwn.net> wrote:

>> Exception occurred:
>>   File "/usr/lib/python3.5/site-packages/docutils/writers/_html_base.py", line
>> 671, in depart_document
>>     assert not self.context, 'len(context) = %s' % len(self.context)
>> AssertionError: len(context) = 1
>
> I've just started getting that kind of stuff on the F25 box.  Some recent
> update clearly broke things; not fun.

My Python fu is weak but it looks like 'context' may be a stack where
the number of pops didn't match the number of pushes?

No clue how to fix that, though.

-- 
Jim

Re: making documentation targets on v4.10 with Fedora 25

[Jonathan Corbet]

On Mon, 20 Feb 2017 12:19:24 -0700
Jim Davis <jim.epost@gmail.com> wrote:

> Exception occurred:
>   File "/usr/lib/python3.5/site-packages/docutils/writers/_html_base.py", line
> 671, in depart_document
>     assert not self.context, 'len(context) = %s' % len(self.context)
> AssertionError: len(context) = 1

Just in case you've not been watching the other conversation, this
failure is due to a nifty API change — yet another one — by the docutils
folks.  Current Sphinx has a workaround; if you update an F25 system the
build will work again.

Sigh.

jon