> Am 14.08.2017 um 18:26 schrieb Randy Dunlap <[email protected]>:
>
> On 08/13/2017 11:46 PM, Markus Heiser wrote:
>> Hi Randy,
>>
>>> Am 13.08.2017 um 19:29 schrieb Randy Dunlap <[email protected]>:
>>>
>>> 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 [email protected]
> 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 [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
