Re: docs build questions (update)

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



> Am 14.08.2017 um 18:26 schrieb Randy Dunlap <rdunlap@xxxxxxxxxxxxx>:
> 
> On 08/13/2017 11:46 PM, Markus Heiser wrote:
>> Hi Randy,
>> 
>>> Am 13.08.2017 um 19:29 schrieb Randy Dunlap <rdunlap@xxxxxxxxxxxxx>:
>>> 
>>> 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".

Interesting, this comes from :

.. kernel-doc:: tools/testing/selftests/kselftest_harness.h
    :doc: example

Wich was added with commit 7e6a32abdd

The problem here, this is a special section (example) ..

+/**
+ * DOC: example
+ *
+ * .. code-block:: c
+ *
+ *    #include "../kselftest_harness.h"
+ *
+ *    TEST(standalone_test) {
+ *      do_some_stuff;
+ *      EXPECT_GT(10, stuff) {
+ *         stuff_state_t state;
+ *         enumerate_stuff_state(&state);
+ *         TH_LOG("expectation failed with state: %s", state.msg);

The kernel-doc parser (in '-rst' mode) has no special handling for such
'example' sections. The parser makes replaces like in regular text sections.

We can test this by ..

./scripts/kernel-doc -rst -function example tools/testing/selftests/kselftest_harness.h

.. code-block:: c

   #include "../kselftest_harness.h"

   TEST(standalone_test) {
     do_some_stuff;
     EXPECT_GT(10, stuff) {
        stuff_state_t state;
        enumerate_stuff_state(:c:type:`state`);
        TH_LOG("expectation failed with state: ``s``", state.msg);
     }

Here we see the :c:type:`state` and other replacements made by
the kernel-doc parser.

IMO, the ..

+ * .. code-block:: c

should not bee needed for example sections, the parser should
output example sections as reST code blocks or et least as
reST literals.

Any thoughts?

-- Markus --





> 
> ~~~~~~~~~~~~~~~~~~~~
> 
> 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 majordomo@xxxxxxxxxxxxxxx
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

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



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux