Re: [PATCH 0/7] doc-rst: sphinx sub-folders & parseheaders directive

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

 



Am 17.08.2016 um 07:44 schrieb Markus Heiser <markus.heiser@xxxxxxxxxxx>:

> 
> @Daniel: I added you to this discussion. May you are interested in, 
> it is about the parse-headers functionality from Mauro.
> 
> Am 16.08.2016 um 20:22 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx>:
> 
>> Em Mon, 15 Aug 2016 10:21:07 +0200
>> Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
>> 
>>> Am 14.08.2016 um 20:09 schrieb Jonathan Corbet <corbet@xxxxxxx>:
> 
> ...
> 
>>>> but stopped at parse-header.
>>>> At this point, I have a few requests.  These are in approximate order of
>>>> decreasing importance, but they're all important, I think.
>> 
>> After writing the PDF support, I'm starting to think that maybe we
>> should migrate the entire functionality to the Sphinx extension.
>> The rationale is that we won't need to be concerned about output
>> specific escape codes there.
> 
> What do you mean with "output specific escape codes"? This: 
> 
> <SNIP>----
> #
> # Add escape codes for special characters
> #
> $data =~ s,([\_\`\*\<\>\&\\\\:\/\|]),\\$1,g;
> 
> $data =~ s,DEPRECATED,**DEPRECATED**,g;
> <SNIP>----
> 
> will be resist, even if you implement it in python.
> 
> 
>>>> - The new directive could really use some ... documentation.  Preferably in
>>>> kernel-documentation.rst with the rest.  What is parse-header, how does
>>>> it differ from kernel-doc, why might a kernel developer doing
>>>> documentation want (or not want) to use it?  That's all pretty obscure
>>>> now.  If we want others to jump onto this little bandwagon of ours, we
>>>> need to make sure it's all really clear.  
>>> 
>>> This could be answered by Mauro.
>> 
>> We use it to allow including an entire header file as-is at the
>> documentation, and cross-reference it with the documents.
>> 
>> IMO, this is very useful to document the ioctl UAPI. There, the most
>> important things to be documented are the ioctl themselves. We don't
>> have any way to document via kernel-doc (as they're #define macros).
>> 
>> Also, when documenting an ioctl, we want to document the structures
>> that are used (most media ioctls use a struct instead of a single value).
>> 
>> So, what we do is that we write a proper description for the ioctl and
>> everything related to it outside the source code. As we want to be
>> sure that everything in the header is documented, we use the
>> "parse-header.pl" (ok, this name really sucks) to create cross-references
>> between the header and the documentation itself.
>> 
>> So, it is actually a script that replaces all occurrences of typedefs,
>> defines, structs, functions, enums into references to the uAPI
>> documentation.
>> 
>> This is is somewhat equivalent to:
>> 	.. code-block:: c
>> 
>> Or, even better, it resembles the Doxygen's \example directive:
>> 	https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdexample
>> 
>> With produces a parsed file, like this one:
>> 	https://linuxtv.org/docs/libdvbv5/dvb-fe-tool_8c-example.html
>> 
>> Except that:
>> 
>> 1) It doesn't randomly painting the file;
>> 
>> 2) All places where the a typedef, define, struct, struct member,
>> function or enum exists are replaced by a cross-reference to the
>> documentation (except if explicitly defined to not do that, via a
>> configuration file).
>> 
>> That, plus the nitpick mode at Sphinx, allows us to check what
>> parts of the uAPI file aren't documented.
>> 
>>>> - Along those lines, is parse-header the right name for this thing?
>>>> "Parsing" isn't necessarily the goal of somebody who uses this directive,
>>>> right?  They want to extract documentation information.  Can we come up
>>>> with a better name?  
>>> 
>>> Mauro, what is your suggestion and how would we go on in this topic?
>> 
>> Maybe we could call it as: "include-c-code-block" or something similar.
> 
> Hmm, that's not any better, IMHO ... there is a 'parsed-literal' so, what's
> wrong with a 'parsed-header' directive or for my sake ' parse-c-header'.
> IMHO it is very unspecific what this directive does and it might be changed in
> the near future if someone (e.g. Daniel [1]) see more use cases then the one yet.
> 
> [1] https://www.mail-archive.com/linux-media%40vger.kernel.org/msg101129.html
> 
> -- Markus --
> 

One more thought; parse-header and kernel_doc, are parsing C code.
But both implement their own C-parser ... may it is time to look
for a more general parser solution:

   * http://git.kernel.org/cgit/devel/sparse/sparse.git
   * https://github.com/eliben/pycparser

Only read the documentation of pycparser, sound promising to me.
With something like "parse_file" we could parse the headers

   * https://github.com/eliben/pycparser/blob/master/pycparser/__init__.py#L54

and with subclassing the "CGenerator" class and overwriting some visit-methods:

   * https://github.com/eliben/pycparser/blob/master/pycparser/c_generator.py#L12

we can produce the reST output. There is a small example parsing C to
an AST and back to C:

https://github.com/eliben/pycparser/blob/master/examples/c-to-c.py#L21

-- Markus--
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