Re: docs build questions (update)

[Randy Dunlap]

On 08/13/2017 11:46 PM, Markus Heiser wrote:
> Hi Randy,
> 
>> Am 13.08.2017 um 19:29 schrieb Randy Dunlap :
>>
>> Hi,
>>
>> [on linux v4.13-rc4]
>>
>>> sphinx-build --version
>> Sphinx (sphinx-build) 1.2.3
> 
> see "Sphinx Install" Documentation/doc-guide/sphinx.rst (ATM in Jon's 
> docs-next)
> 
>  The ReST markups currently used by the Documentation/ files are meant to be
>  built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
>  PDF outputs, it is recommended to use version 1.4.6 or upper.

Hi,
Most of the previous problems are now fixed.  Thanks.


> sphinx-build --version
Sphinx (sphinx-build) 1.3.1

and Linux v4.13-rc5:


lnx-413-rc5/Documentation/doc-guide/sphinx.rst:121: ERROR: Unknown target name: 
"sphinx c domain".



WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno 
../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec can't 
decode byte 0xe2 in position 6368: ordinal not in range(128)

probably in middle this block (/wrapped/):

 * The @buffer2 buffer parameter is normally NULL, except when the received
 * TS packets have crossed the last address of the circular buffer and
 * ”wrapped” to the beginning of the buffer. In the latter case the @buffer1
 * parameter would contain an address within the circular buffer, while the
 * @buffer2 parameter would contain the first address of the circular buffer.


-- 
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: docs build questions

[Jani Nikula]

On Mon, 14 Aug 2017, Randy Dunlap  wrote:
> On 08/13/2017 11:46 PM, Markus Heiser wrote:
>> Hi Randy,
>> 
>>> Am 13.08.2017 um 19:29 schrieb Randy Dunlap :
>>> Lots of ERRORs where a doc comment is of the form GPP_ (ending with a '_'):
>>>
>>> ../block/bio.c:404: ERROR: Unknown target name: "gfp".
>> 
>> Yes, this is a conflict since comments are reST Markup.
>> 
>>  https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
>> 
>> In sources we like to use FOO_ (ending with a '_'), which is a
>> hyperlink markup in reST:
>> 
>>  http://www.sphinx-doc.org/en/stable/rest.html#hyperlinks
>> 
>> The only solution I see is to replace FOO_ with ``FOO_``
>
> I guess that's OK in doc files, but most of these comments are in source files
> and requiring ``xyz_`` there is not nice.

I assume very few actual symbols end in underscore, and this is more of
a question of referencing a group of FOO_ prefixed symbols. In these
cases, I prefer using FOO_* as it both avoids the problem and makes
perfect sense in plain text.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: docs build questions

[Randy Dunlap]

On 08/13/2017 11:46 PM, Markus Heiser wrote:
> Hi Randy,
> 
>> Am 13.08.2017 um 19:29 schrieb Randy Dunlap :
>>
>> Hi,
>>
>> [on linux v4.13-rc4]
>>
>>> sphinx-build --version
>> Sphinx (sphinx-build) 1.2.3
> 
> see "Sphinx Install" Documentation/doc-guide/sphinx.rst (ATM in Jon's 
> docs-next)
> 
>  The ReST markups currently used by the Documentation/ files are meant to be
>  built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
>  PDF outputs, it is recommended to use version 1.4.6 or upper.
> 
> Sorry for the mess in the past. Mauro has now cleared this up for us / thanks 
> Mauro
> 
>> I'm getting some docs build errors and warnings. Do I need a newer
>> version of Sphinx or some options added?
> 
> No options needed, update Sphinx should help.

OK, will do, thanks.

>> ~~~
>>
>> Lots of ERRORs where a doc comment is of the form GPP_ (ending with a '_'):
>>
>> ../block/bio.c:404: ERROR: Unknown target name: "gfp".
> 
> Yes, this is a conflict since comments are reST Markup.
> 
>  https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
> 
> In sources we like to use FOO_ (ending with a '_'), which is a
> hyperlink markup in reST:
> 
>  http://www.sphinx-doc.org/en/stable/rest.html#hyperlinks
> 
> The only solution I see is to replace FOO_ with ``FOO_``

I guess that's OK in doc files, but most of these comments are in source files
and requiring ``xyz_`` there is not nice.


-- 
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: docs build questions

[Markus Heiser]

> Am 14.08.2017 um 09:45 schrieb Jani Nikula :
> 
> On Mon, 14 Aug 2017, Markus Heiser  wrote:
>> see "Sphinx Install" Documentation/doc-guide/sphinx.rst (ATM in Jon's 
>> docs-next)
>> 
>> The ReST markups currently used by the Documentation/ files are meant to be
>> built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
>> PDF outputs, it is recommended to use version 1.4.6 or upper.
>> 
>> Sorry for the mess in the past. Mauro has now cleared this up for us /
>> thanks Mauro
> 
> If you require a specific Sphinx version or higher, the thing to do is
> specify needs_sphinx in conf.py so that Sphinx gives you a proper error
> message:
> 
> """
> Sphinx version error:
> This project needs at least Sphinx v1.3 and therefore cannot be built with 
> this version.
> """

Since this is a real bug in conf.py I fixed it.

> It's a bit clunky, but you could even specify -Dneeds_sphinx=1.4 from
> the Makefile for the PDF build, to have different requirements for
> different builders. AFAICT you can't get at the builder directly from
> conf.py.

I still hesitate to patch Documentation/Makefile. I wan't add any more
complexity. ATM the script ./scripts/sphinx-pre-install should be enough.
Anyway; thanks for the hint.

-- Markus --

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: docs build questions

[Jani Nikula]

On Mon, 14 Aug 2017, Markus Heiser  wrote:
> see "Sphinx Install" Documentation/doc-guide/sphinx.rst (ATM in Jon's 
> docs-next)
>
>  The ReST markups currently used by the Documentation/ files are meant to be
>  built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
>  PDF outputs, it is recommended to use version 1.4.6 or upper.
>
> Sorry for the mess in the past. Mauro has now cleared this up for us /
> thanks Mauro

If you require a specific Sphinx version or higher, the thing to do is
specify needs_sphinx in conf.py so that Sphinx gives you a proper error
message:

"""
Sphinx version error:
This project needs at least Sphinx v1.3 and therefore cannot be built with this 
version.
"""

It's a bit clunky, but you could even specify -Dneeds_sphinx=1.4 from
the Makefile for the PDF build, to have different requirements for
different builders. AFAICT you can't get at the builder directly from
conf.py.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: docs build questions

[Markus Heiser]

Hi Randy,

> Am 13.08.2017 um 19:29 schrieb Randy Dunlap :
> 
> Hi,
> 
> [on linux v4.13-rc4]
> 
>> sphinx-build --version
> Sphinx (sphinx-build) 1.2.3

see "Sphinx Install" Documentation/doc-guide/sphinx.rst (ATM in Jon's docs-next)

 The ReST markups currently used by the Documentation/ files are meant to be
 built with ``Sphinx`` version 1.3 or upper. If you're desiring to build
 PDF outputs, it is recommended to use version 1.4.6 or upper.

Sorry for the mess in the past. Mauro has now cleared this up for us / thanks 
Mauro

> I'm getting some docs build errors and warnings. Do I need a newer
> version of Sphinx or some options added?

No options needed, update Sphinx should help.

> Documentation/input/devices/xpad.rst:137: ERROR: Error in "code-block" 
> directive:
> unknown option: "caption".
> 
> where those lines are:
> .. code-block:: none
>  :caption: dump from InterAct PowerPad Pro (Germany)

Sphinx version

> 
> ~
> 
> Documentation/doc-guide/sphinx.rst:121: ERROR: Unknown target name: "sphinx c 
> domain".

Sphinx version

> 
> ~~~
> 
> Lots of ERRORs where a doc comment is of the form GPP_ (ending with a '_'):
> 
> ../block/bio.c:404: ERROR: Unknown target name: "gfp".

Yes, this is a conflict since comments are reST Markup.

 https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html

In sources we like to use FOO_ (ending with a '_'), which is a
hyperlink markup in reST:

 http://www.sphinx-doc.org/en/stable/rest.html#hyperlinks

The only solution I see is to replace FOO_ with ``FOO_``

> 
> 
> 
> and later I get a fatal error:
> 
> Exception occurred:
> File ".../lnx-413-rc4/Documentation/sphinx/kfigure.py", line 240, in 
> convert_image
>   translator.builder.imagedir,
> AttributeError: 'StandaloneHTMLBuilder' object has no attribute 'imagedir'

Sphinx version.


-- Markus 
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html