From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932843AbcFJOR5 (ORCPT ); Fri, 10 Jun 2016 10:17:57 -0400 Received: from mga09.intel.com ([134.134.136.24]:2552 "EHLO mga09.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932661AbcFJORx (ORCPT ); Fri, 10 Jun 2016 10:17:53 -0400 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.26,450,1459839600"; d="scan'208";a="999326982" From: Jani Nikula To: Jonathan Corbet Cc: Jani Nikula , Markus Heiser , Daniel Vetter , Grant Likely , Mauro Carvalho Chehab , Keith Packard , LKML , linux-doc@vger.kernel.org, Hans Verkuil Subject: [docs-next PATCH 9/9] Documentation/sphinx: add support for specifying extra export files Date: Fri, 10 Jun 2016 17:17:03 +0300 Message-Id: <03d35d9ec4ae50afeafc3ab26d8207b7069f3cba.1465567017.git.jani.nikula@intel.com> X-Mailer: git-send-email 2.1.4 In-Reply-To: References: In-Reply-To: References: Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Let the user specify file patterns where to look for the EXPORT_SYMBOLs in addition to the file with kernel-doc comments. This is directly based on the -export-file FILE option added to kernel-doc in "kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs", but we extend that with globbing patterns in the Sphinx extension. The file patterns are added as options to the :export: and :internal: arguments of the kernel-doc directive. For example, to extract the documentation of exported functions from include/net/mac80211.h: .. kernel-doc:: include/net/mac80211.h :export: net/mac80211/*.c Without the file pattern, no exported functions would be found, as the EXPORT_SYMBOLs are placed in the various source files under net/mac80211. The matched files are also added as dependencies on the document in Sphinx, as they may affect the output. This is one of the reasons to do the globbing in the Sphinx extension instead of in scripts/kernel-doc. The file pattern remains optional, and is not needed if the kernel-doc comments and EXPORT_SYMBOLs are placed in the source file passed in as the main argument to the kernel-doc directive. This is the most common case across the kernel source tree. Signed-off-by: Jani Nikula --- Documentation/sphinx/kernel-doc.py | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py index d6a76f9a0ba5..dedb24e3bb7a 100644 --- a/Documentation/sphinx/kernel-doc.py +++ b/Documentation/sphinx/kernel-doc.py @@ -31,6 +31,7 @@ import os import subprocess import sys import re +import glob from docutils import nodes, statemachine from docutils.statemachine import ViewList @@ -44,8 +45,8 @@ class KernelDocDirective(Directive): option_spec = { 'doc': directives.unchanged_required, 'functions': directives.unchanged_required, - 'export': directives.flag, - 'internal': directives.flag, + 'export': directives.unchanged, + 'internal': directives.unchanged, } has_content = False @@ -54,6 +55,7 @@ class KernelDocDirective(Directive): cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] + export_file_patterns = [] # Tell sphinx of the dependency env.note_dependency(os.path.abspath(filename)) @@ -63,14 +65,21 @@ class KernelDocDirective(Directive): # FIXME: make this nicer and more robust against errors if 'export' in self.options: cmd += ['-export'] + export_file_patterns = str(self.options.get('export')).split() elif 'internal' in self.options: cmd += ['-internal'] + export_file_patterns = str(self.options.get('internal')).split() elif 'doc' in self.options: cmd += ['-function', str(self.options.get('doc'))] elif 'functions' in self.options: for f in str(self.options.get('functions')).split(): cmd += ['-function', f] + for pattern in export_file_patterns: + for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): + env.note_dependency(os.path.abspath(f)) + cmd += ['-export-file', f] + cmd += [filename] try: -- 2.1.4