From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id C3B3543F4A; Mon, 29 Apr 2024 15:49:44 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 421B54025C; Mon, 29 Apr 2024 15:49:44 +0200 (CEST) Received: from mail-pj1-f41.google.com (mail-pj1-f41.google.com [209.85.216.41]) by mails.dpdk.org (Postfix) with ESMTP id BE426400D6 for ; Mon, 29 Apr 2024 15:49:42 +0200 (CEST) Received: by mail-pj1-f41.google.com with SMTP id 98e67ed59e1d1-2b1cfae51a5so581168a91.2 for ; Mon, 29 Apr 2024 06:49:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=iol.unh.edu; s=unh-iol; t=1714398582; x=1715003382; darn=dpdk.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=xvwp9rel7EEtm1809htzRw9JUHtViTIAN+OsEDwn/Vs=; b=VwHjLyKNIFYukogb7NeEpn9gRhL+ux9xX9Ie/7GstxZ3OBnr19XI9o1zHH09xGwTWc tTL2NbDXOhYynG4t1nXbkJFyeRdK6zRL9UZu2iP87RJ/MeShJJMIAmxW0YF+SZZhOZGH 6UU44jhLf1OgCSy8McE+UYzH3nCmanQbZA9+c= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1714398582; x=1715003382; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=xvwp9rel7EEtm1809htzRw9JUHtViTIAN+OsEDwn/Vs=; b=g3UAbvGv9EuMVU8eo4UZQxfkOd6sBz8CQnxdrjQSDn7JmqkC+kMsZvZW7X8kaC3njL r50PdMWGZfrad21kHJ4UtemYgFSI7II8MJWNh6RcS0MYznMmoi5pKnjg5QYA8vvEHeKq HU/ZVXioVf7DM41eH1L5BXbaRuMns1XdDB8dCXiuXLZBWVh2kX4EJXei5tGSOPA1Sy13 22aGS+72JlIT5QVD4JkjUa9jvpYvh063z0EF5Vjw+GTLkzU0R+OsAxLTfscc9Wv9IhBD MVkYvrjmKYEKH/ag3h3eknoFqvKxFR5Hoy1ddJnqKdaiamDOpI/4Hx5dJcc6lEq1FCCH 3klA== X-Forwarded-Encrypted: i=1; AJvYcCXGEBdDRRfpPKSAqoKV6wnHiFWas4nOZZhNS5odieSD2ZoUMKX54ioykMdNd/sLmRoqGb8QyeJkvkm/rYg= X-Gm-Message-State: AOJu0YxT9JO8eWcLPBQJs0mgne4Akcr4WmNfJT0o9LV/b86AXX/zCvLo 4cZy1D76hkdwAnm9O4I3atH0g9AGML2gehfmvadLa6OjB2PBvk796QFMUeprVrUKgveMYRPvRFi mxO+jqjjHsMaIzz0t6EucZcANmJcA4H2GxiJ0Yw== X-Google-Smtp-Source: AGHT+IH/Bq5hOip40UCoVUti+nKmXZIcTyZTwFmS6NO/Xjc4b68/2qG1WaKl585YrIHaPLAXNw831E+vRKbA5eB0hLM= X-Received: by 2002:a17:90a:6d02:b0:2a6:d064:15d5 with SMTP id z2-20020a17090a6d0200b002a6d06415d5mr9753460pjj.18.1714398581778; Mon, 29 Apr 2024 06:49:41 -0700 (PDT) MIME-Version: 1.0 References: <20231115133606.42081-1-juraj.linkes@pantheon.tech> <20240412101405.94377-1-juraj.linkes@pantheon.tech> In-Reply-To: <20240412101405.94377-1-juraj.linkes@pantheon.tech> From: Jeremy Spewock Date: Mon, 29 Apr 2024 09:49:30 -0400 Message-ID: Subject: Re: [PATCH v4 0/3] dts: API docs generation To: =?UTF-8?Q?Juraj_Linke=C5=A1?= Cc: thomas@monjalon.net, Honnappa.Nagarahalli@arm.com, bruce.richardson@intel.com, probb@iol.unh.edu, paul.szczepanek@arm.com, Luca.Vizzarro@arm.com, npratte@iol.unh.edu, dev@dpdk.org Content-Type: text/plain; charset="UTF-8" X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org > The patchset contains the .rst sources which Sphinx uses to generate the > html pages. These were first generated with the sphinx-apidoc utility > and modified to provide a better look. The documentation just doesn't > look that good without the modifications and there isn't enough > configuration options to achieve that without manual changes to the .rst > files. This introduces extra maintenance which involves adding new .rst > files when a new Python module is added or changing the .rst structure > if the Python directory/file structure is changed (moved, renamed > files). This small maintenance burden is outweighed by the flexibility > afforded by the ability to make manual changes to the .rst files. > > We can merge this patch when: > 1. We agree on the approach with manually modifying the files. > This approach is, in my opinion, much better than just generating the > .rst files every time, +1 for manually modifying .rst files. The .rst files are very simple, and I think the added flexibility to change headers or tweak things as needed is a big benefit over just auto-generating and not having as much control. Additionally, if it just so happens that the auto-generated file looks fine and the developer doesn't want to make changes, they can still just generate it themselves and it fits right in, so this approach still works with the other regardless. > 2. Bruce sends his ack on the meson modifications. I believe we had a > positive reaction on the previous version, but not this one. > 3. The link to DTS API docs that was added to doxy-api-index.md is > satisfactory. I think Thomas could check this? > > -- > 2.34.1 >