From patchwork Thu Apr 25 20:01:23 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 162890 Delivered-To: patch@linaro.org Received: by 2002:a02:c6d8:0:0:0:0:0 with SMTP id r24csp2369971jan; Thu, 25 Apr 2019 13:01:44 -0700 (PDT) X-Google-Smtp-Source: APXvYqxrAl0Zt+FMj9D/+S8ARd3BkLzYyR6IZ5xgs1bv+6CrGLq1L8qSpWp/3onSzfzF57cL4N4T X-Received: by 2002:aa7:8719:: with SMTP id b25mr3292957pfo.90.1556222504009; Thu, 25 Apr 2019 13:01:44 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1556222504; cv=none; d=google.com; s=arc-20160816; b=eC0sachQ4PKkdHytpin0Im1vxE6WTGgDeSx0fF4XRMKvlN7hMFBVWc8yClY076QnW1 IsNsRdpuBudcNqHB2cIENeCqko6pMvLexdh6z4KA9+QB/PJ63fepLj5QjILgkljzRtOg knSXYFSlNo0Ju98Nrn+Ic9RExLnggvdqp+ifY4sqAFBnzYAj/wAa74Jxg7RBfkPf7yuF lZOwcoEdE98LWMI7TETD2wAw8Q8SNtJUktkuhtDU62+pkHHf2jy1Cd0QtRi/3V2rLlAg fp7u673w54aJFOBSf700l9fHjfy3MjXzA/ArGtdeOoJjebduX2pPOkk63IrsKPpk1phI KNzg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :message-id:date:subject:cc:to:from; bh=wl4u6u4OrlAnpUfQ4tHZv1ibcQN86H6zOeYazkZ358E=; b=xujzbfKnxYVSA7GcP5qaBhdI/60GY1u7t2MEk01AB1tl3Jar7iX+I6KncsGeGjCeYB VNSf5B0AiOndWZuCiUwd16cetxsC8QNfgYAoqkyD0ePfi9qqPOXUm2XXxcvhgvT/efi4 sVduUi8nwOBWROiWE56qiU36W8kLsXTan631kGlf2ZLrmq4lt7L+cEMe/c5hwjscLz1G pBKPc2Mnuu1jnYqf/T87uicAhDuyt67yjaTEVA6K6p+WN3yZWJABMj72SXUPgJsR1Y6e DmIprk862E06jpJs7qEhLTjnGEUyr40LkaYuQeg4MayBlADrfFTnl1JhcgQJjK0fMGPj lZNg== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id y6si138864plt.365.2019.04.25.13.01.43; Thu, 25 Apr 2019 13:01:43 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730795AbfDYUBm (ORCPT + 30 others); Thu, 25 Apr 2019 16:01:42 -0400 Received: from ms.lwn.net ([45.79.88.28]:43874 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1728999AbfDYUBl (ORCPT ); Thu, 25 Apr 2019 16:01:41 -0400 Received: from meer.lwn.net (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id D345B2B7; Thu, 25 Apr 2019 20:01:40 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, Matthew Wilcox , Mauro Carvalho Chehab , Jonathan Corbet Subject: [PATCH 0/2] RFC: Automatic :c:func: annotation in the sphinx build Date: Thu, 25 Apr 2019 14:01:23 -0600 Message-Id: <20190425200125.12302-1-corbet@lwn.net> X-Mailer: git-send-email 2.21.0 MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org There have been (justified) complaints that writing function() as :c:func:`function()` in RST documents is obnoxious for both writers and readers. The following patch adds an extension to the sphinx build to add this annotation automatically instead. As is always the case, recognizing "function()" is easy; recognizing the places where we should *not* mangle things is harder. Patch #2 removes all of the :c:func: annotations from xarray.rst - over 150 of them - to highlight the difference. The only change in the output is cross references added for a couple of functions that were not annotated in the original version. This adds some processing during the docs build, but my attempts to measure the slowdown showed that it is less than the noise between builds. The output from a full docs build with these patches applied can be seen at https://static.lwn.net/kerneldoc/. Jonathan Corbet (2): Docs: An initial automarkup extension for sphinx docs: remove :c:func: annotations from xarray.rst Documentation/conf.py | 3 +- Documentation/core-api/xarray.rst | 270 ++++++++++++++--------------- Documentation/sphinx/automarkup.py | 90 ++++++++++ 3 files changed, 227 insertions(+), 136 deletions(-) create mode 100644 Documentation/sphinx/automarkup.py -- 2.21.0