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

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

 



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

> Regards,
> Mauro

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