From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id iDn3N8v7ZGPPAgEAbAwnHQ (envelope-from ) for ; Fri, 04 Nov 2022 12:47:23 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id iDvNN8v7ZGN9dgAAauVa8A (envelope-from ) for ; Fri, 04 Nov 2022 12:47:23 +0100 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id AB8B821ADD for ; Fri, 4 Nov 2022 12:47:23 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqv9N-0001Tz-V1; Fri, 04 Nov 2022 07:46:18 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oqv8t-0001R2-Tf for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 07:45:49 -0400 Received: from ciao.gmane.io ([116.202.254.214]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oqv8p-0001La-G9 for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 07:45:44 -0400 Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1oqv8n-0007tU-LP for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 12:45:41 +0100 X-Injected-Via-Gmane: http://gmane.org/ To: emacs-orgmode@gnu.org From: Max Nikulin Subject: Re: Docstrings and literate programming (good practices?) Date: Fri, 4 Nov 2022 18:45:33 +0700 Message-ID: References: <87bkpqbwef.fsf@posteo.net> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.2.2 Content-Language: en-US In-Reply-To: Received-SPF: pass client-ip=116.202.254.214; envelope-from=geo-emacs-orgmode@m.gmane-mx.org; helo=ciao.gmane.io X-Spam_score_int: 26 X-Spam_score: 2.6 X-Spam_bar: ++ X-Spam_report: (2.6 / 5.0 requ) BAYES_00=-1.9, DKIM_ADSP_CUSTOM_MED=0.001, FORGED_GMAIL_RCVD=1, FORGED_MUA_MOZILLA=2.309, FREEMAIL_FORGED_FROMDOMAIN=0.001, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, NICE_REPLY_A=-0.001, NML_ADSP_CUSTOM_MED=0.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "Emacs-orgmode" Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1667562443; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=uGq+KxTFvH5yrVfOUqt/NQEzDLglONbhIY2JOcJB9FA=; b=hV9ECR5+gjbChEL2BIqYi6gsgqy1dGumAARaqhm72h3qgA2SlbATq64eGRBKQQvGvNYnGh TNEDV9/7X8fS7VJ0ZcdEZhf/8X717G5CpMrWg7sQEB0zuBn/zoO/EKRr3W1+JA9BaG7K+6 Y+ZlDHDJ1yR8DtOAd7tFoST3JT7wkEmqBanapwjBS10L6mvqusr+pTkiaH1+RUZXkvmNlv UKzxNlHiYLBfxKXp5bXgOBTGZ+UJOMhDVOkOG1wAGCnJh09KMKE6MxejdK7MYLREmjOSaz np3G0bdPbDlqIcIqkC9MtwkzL3EuIDQxeqMf9A0Oy2AVbnCVzNd2S5vv6GgvfA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667562443; a=rsa-sha256; cv=none; b=B4DO1j5bsuCTtjnS8qAYvckKmcuQhE/kyK4y3idPU4YMWEU+jtdWzdGRqwkvCBlG2rTQg8 5DkGIzv1Fij3K5JQCERgA5fkEP7EBVCewnpepM7VZ4G3euZVuMpsXPj7zthzrsANAqNCut TgtD2IIupC6SeoEO3kdQvavRNWmA3oBKZiQBpXbuiuZLNoOU7DawHOQPjBsi6XiFc7N54o f/zAJliDU6ggSwItM/lG8glbjaV1/wD204BgaMXgbc3qwBde184R+Ptd2+Rwt096F9ML8Q hUU6XqvmHw9AWVIUJDXhdWa7NMV2+KIyvjS5QtiNnwxhEN0MLBdA0l/JzD912Q== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=fail reason="SPF not aligned (relaxed), No valid DKIM" header.from=gmail.com (policy=none); spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: 1.90 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=fail reason="SPF not aligned (relaxed), No valid DKIM" header.from=gmail.com (policy=none); spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: AB8B821ADD X-Spam-Score: 1.90 X-Migadu-Scanner: scn0.migadu.com X-TUID: K4wDEYitF1We On 04/11/2022 10:03, Samuel Wales wrote: > > for example, you have a body of non-literate elisp code, and you have > a manual. it could be redundant to describe commands and what they do > and their options, if the docstrings are good. There is Sphinx in Python world that allows to combine guide pages with API docs extracted from source files: classes, functions, variables, modules (files). Some introduction and API reference may work well. I tried it, but without going deeper I did not manage to achieve the same quality as I saw for some packages at readthedocs. https://www.sphinx-doc.org/en/master/ What I miss in texinfo is a feature similar to Intersphinx https://www.sphinx-doc.org/en/master/usage/quickstart.html#intersphinx To generate external references in HTML pages, an index file may be downloaded. As a result anchors in docs or function names are linked to proper files, anchors are formatted with section names as their description. https://docs.python.org likely uses another tool, but the approach is often the same: general description and docstrings. I think, Org manual published on the web site would benefit from links to HTML API reference generated from docstrings. P.S. Pages generated by doxygen may be convenient as well. It is nice to have details related to functions and classes linked from overview, design description, a guide how this API should be used. Of course, it works only if such pages are written and added to doxygen config.