On 9/10/25 2:53 AM, Bagas Sanjaya wrote:
> On Tue, Sep 09, 2025 at 10:14:42PM +0200, Andrey Ryabinin wrote:
>> +There are _V forms of many KSTATE_ macros to load fields for version
>> dependent fields, e.g.
>
> Escape the trailing underscore (i.e. KSTATE\_).
>
>> +Addition of new field can be done as version dependent field by using _V
>> form of
>> +KSTATE_ macro:
>
> Ditto.
>
>> +Subsections
>> +-----------
>> +Another option is adding subsection to kstate_description. A subsection is
>> +additional kstate_description which linked to the main one:
>> +
>> +struct kstate_description test_state_v2 = {
>> + .name = "test_v2",
>> + .id = KSTATE_TEST_ID_V2,
>> + .fields = (const struct kstate_field[]) {
>> + KSTATE_BASE_TYPE(i, struct kstate_test_data, int),
>> + KSTATE_END_OF_LIST()
>> + },
>> +};
>> +
>> +struct kstate_description test_state = {
>> + ......
>> + .subsections = (const struct kstate_description *[]){
>> + &test_state_v2,
>> + NULL
>> + },
>> +};
>
> Sphinx errors out on struct snippets like above:
>
> Documentation/core-api/kstate.rst:17: WARNING: Inline emphasis start-string
> without end-string. [docutils]
> Documentation/core-api/kstate.rst:17: WARNING: Inline emphasis start-string
> without end-string. [docutils]
> Documentation/core-api/kstate.rst:21: WARNING: Definition list ends without a
> blank line; unexpected unindent. [docutils]
> Documentation/core-api/kstate.rst:28: ERROR: Unexpected indentation.
> [docutils]
> Documentation/core-api/kstate.rst:32: WARNING: Block quote ends without a
> blank line; unexpected unindent. [docutils]
> Documentation/core-api/kstate.rst:33: WARNING: Definition list ends without a
> blank line; unexpected unindent. [docutils]
> Documentation/core-api/kstate.rst:84: ERROR: Unexpected indentation.
> [docutils]
> Documentation/core-api/kstate.rst:100: ERROR: Unexpected indentation.
> [docutils]
> Documentation/core-api/kstate.rst:102: WARNING: Block quote ends without a
> blank line; unexpected unindent. [docutils]
> Documentation/core-api/kstate.rst:103: WARNING: Definition list ends without
> a blank line; unexpected unindent. [docutils]
> Documentation/core-api/kstate.rst:106: CRITICAL: Unexpected section title or
> transition.
>
> ...... [docutils]
>
> reStructuredText markup error!
>
> I have to wrap them in literal code blocks:
>
Thanks, I will make sure to check that the documentation builds next time.
