Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <15942593-5ec7-77a6-8637-61ca495d7528@amd.com>
Date:   Thu, 1 Dec 2022 14:40:33 -0600
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.4.2
Subject: Re: [PATCH] docs: Integrate rustdoc into Rust documentation
Content-Language: en-US
To:     Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
Cc:     corbet@lwn.net, ojeda@kernel.org, bilbao@vt.edu,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        konstantin@linuxfoundation.org, Akira Yokosawa <akiyks@gmail.com>
References: <20221130220825.1545758-1-carlos.bilbao@amd.com>
 <CANiq72nMY5f85tJJFg7AFsh4YRrKObhurhT8TVawYqoZU+J-Fg@mail.gmail.com>
From:   Carlos Bilbao <carlos.bilbao@amd.com>
In-Reply-To: <CANiq72nMY5f85tJJFg7AFsh4YRrKObhurhT8TVawYqoZU+J-Fg@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?eTUyVnp2WlJOcTRab2ZxWGU2Vm9HajEya0NNTEdhQnViaTRzQjNCS3EwU2p5?=
 =?utf-8?B?WnRzd0IzVTRkYTZjU1MvcVp5Zm4yK1hUcVhiQXZNblFKTFRIWStlNGFaZ2li?=
 =?utf-8?B?YUxHdDJicHJiMVFYVFl3cHA2QWE2a250NllEcE5QQjQwRC81c0xZdEdrdXZH?=
 =?utf-8?B?ajQ3QzdmU09FMEpTcyt4MkRkVUYvNzJWUlRaaXBFWXJXSzdJRUFENFczanNI?=
 =?utf-8?B?VTY2ZENidGhPUGFkTkIrWURFZ1RrRXptb2JySXMxTnZoNG5JQW5DZXg1eTB1?=
 =?utf-8?B?bjJ3TDBoNWFJTy9VYzEzdWhETmhWa1p6U1UzUzVhWjRsdWMwMCswNEdQU3ha?=
 =?utf-8?B?SmJUdVU2azBPTFo0UTFhTUgweGllMzE3VzVBNDF3YmJCa1hIWm9mb04yTWta?=
 =?utf-8?B?QjRHNCtBNlJac1pwcTdvdjIvWXlhQ1hCRVUxRC84NTZQQ2J2cXJpTkdjaG9V?=
 =?utf-8?B?WXQrMngzNHNjUU1TQVlNckdkcnA3SUl2UVNidTNuSjM0SUtZZUJDRUxvR0pE?=
 =?utf-8?B?TGpaM0FQWFF3SmZWR1lBaHJEZ2picCtFY2pJWU5TeHl4ZFVwSzlpamJsVDhj?=
 =?utf-8?B?RXkvNUNlSE9sZVRrYXpvbGMwOVVUWWltamI2MFlSN3E5WUQ2ZXM1TjMydWtN?=
 =?utf-8?B?TzlKMHgzd3dlakRsVlExc0hPLzdNZ3kvaGgrUUdTSTR6T2tUVlZwTURrU1lH?=
 =?utf-8?B?NG91QitlbFN6ZTVBdTFldXpyYjI2K1d5dnp1OCtCcjlCOU81dmxJa2s5R1RP?=
 =?utf-8?B?c3NqUEFhaWNqSi9CZVhvVzV5dUdyeHF6aUNEdVE2UmN2bDdVaUdKenROeWNM?=
 =?utf-8?B?aWZzaWhUR2dodnF6bytTMStraHZ1eGt0ZUNJbHBUUEx1c3M1a2drcXBaM1dP?=
 =?utf-8?B?N0ttYWtKamNvQ1llZWZCZjZWVEtQSEZ3bTg3YldmV3hQL2VrRmRGUUNBOUkv?=
 =?utf-8?B?WU1ZYkJjSTdFUlFDTU14dmdIQTJwUFZZMVVFeUtJUWh5d0hWeG1VVFRFcHpp?=
 =?utf-8?B?UTEvVkdaUnFucFhFWWorV3lDOWVTZTBMbkUxL1ZpWi9hNzV1UFZsK0JrVWVL?=
 =?utf-8?B?OGw4R2ZRQyttMDI5K3AwUUl4OHlMbVZ2M28vRE5XYVVEOExCNS9MOXVSbUVE?=
 =?utf-8?B?U0NESlFxdmVvUHUwYU5NUGZhQTI1a0FZL1RZOHBGcVZYeWg4Y1dKNzJPWEZ4?=
 =?utf-8?B?UUwrODczVnp6NUUrejVHM0hvd0xGZTBkTmRiSkprLzJlQjFNVDBBK0JuV1px?=
 =?utf-8?B?TVlMbEUwcUVvWE94VE1RcHY2azlsNEpVWVd5cmFiRTBCWnA3cTFEZWFKdWhI?=
 =?utf-8?B?ZzI1ekpuM3orQkF1N2tlZmFodis4TDczNjRjSytjdzlGejdCdG9XNFlLZ1Fx?=
 =?utf-8?B?a0pLMFI4N2c4VjlSTSs4eHJ6eFRmTnhmMHhMUzFQRmgvdWhLb2pFVjM4Wm4y?=
 =?utf-8?B?SVZMWEIvK0h1cmtrQWEzdEdKS2Q1RHg4bW8yU0lHUnk2VTRDaCtIN1ZOWEs0?=
 =?utf-8?B?RjdWcUxaYkRJV1hobk1rVzg1OUU5dGMramtCS0lsbDhMbDlJUXp5WHlSUy9O?=
 =?utf-8?B?dGI4ajRYNWlQMmlTR0dkSm5GUjBVT3NaWWF0QWV1dW9aN3ozdVZyL3VKa1lV?=
 =?utf-8?B?R0gyZU81ZXREWU1rZzhqTzU4UTMzemlhZGUyZXAyVzJ4YjQ2YmdodDNFWSt2?=
 =?utf-8?B?Z1NzYzYwWTAvMWFmOTRXbDlHUkkvUHI3VmZGVThOZ2hwbmZ2SHY4WEZBS1FG?=
 =?utf-8?B?R3hLb2FkSkU1eUNGV2JHYzJwT3ZXTXNvZCs5enBKcTR4N24xaVJtNFFhLy9U?=
 =?utf-8?B?dTBLbFNzSHJ5eCtpMTE1eTlBeVZFc2cwK3o0S3VwbCt3RXJrT1V5cmlKdzEw?=
 =?utf-8?B?Yy9OMU1pc3RlQnd4VXVUUUFhMW4wYm9HQ2tXdWVCNEtFYkpadFZENzlpUXRD?=
 =?utf-8?B?RWcrZ2xFQVU0eUFCemFkc2l1SzlrVzJUSW5QTk5LS1ArYmVjbkRkMHE3eW5a?=
 =?utf-8?B?TUkxTG84NWNRZ0E2U0d5UmY4TDhoUVlpWFhwVHAvQm1BRGFERWNUem5Ob3dU?=
 =?utf-8?B?RlNpTWp3TDZpaGdLSEtySVpqWXo0c29raXFUZnJzYzhsY3dnSjlLd3o5WW5X?=
 =?utf-8?Q?K7GHLWI3nGJI1q7oqxlYfsU6h?=
X-OriginatorOrg: amd.com
X-MS-Exchange-CrossTenant-Network-Message-Id: f35ab46e-fcf3-42a8-fdb3-08dad3dc4c76
X-MS-Exchange-CrossTenant-AuthSource: BL1PR12MB5874.namprd12.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 01 Dec 2022 20:40:35.6884
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 3dd8961f-e488-4e60-8e11-a82d994e183d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: Ec5W+ECTeSjsFG+x1l8RXfuam04ZGZgNnNH3/+IIIO/TgTv5o9tBbVO+t5h0BC+mxC8uhuPAlwxfs/oMkrqzwA==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BL1PR12MB5780
X-Spam-Status: No, score=-2.4 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,NICE_REPLY_A,RCVD_IN_DNSWL_NONE,
        RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS autolearn=ham
        autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On 12/1/22 06:42, Miguel Ojeda wrote:

> On Wed, Nov 30, 2022 at 11:08 PM Carlos Bilbao <carlos.bilbao@amd.com> wrote:
>
>> +ifdef CONFIG_RUST
>> +       @make LLVM=1 rustdoc
>> +endif
> The Rust docs should probably be built with the build
> system/config/... as given, whether it is GCC, LLVM, etc. This should
> probably use `$(MAKE)` too; and if you intended to remove the command
> line definitions, `MAKEOVERRIDES` too.


Sounds good.


> By the way, while checking this, I noticed we use some `CONFIG_`s in
> this `Makefile`, but we do not perform a config sync for the `*docs`
> targets, so one needs to do so manually, i.e. it can be a pitfall for
> e.g. `CONFIG_WARN_MISSING_DOCUMENTS` and ` as well as a potential
> `CONFIG_RUST`. Should this be fixed orthogonally, or is it intended?
> (some targets do not need the sync, and the ones that need are
> probably less used, so I guess that could be the reason?).


I don't understand config sync. Perhaps that, e.g. Documentation/Makefile
checks for broken docs, for CONFIG_WARN_MISSING_DOCUMENTS, but we don't
do that for rust/Makefile? I'm not sure, but it does sound orthogonal, yes.


>
>> +Rustdoc output
>> +==============
>> +
>> +If this documentation includes rustdoc-generated HTML, the entry point
>> +can be found `here. <rustdoc/kernel/index.html>`_
> Perhaps this sentence could be moved to the top of the index file, so
> that users do not need two clicks when visiting "Rust"? That way we
> avoid one more file too.


Yes, that will be better :)


>
>> +RUSTDOC_OUTPUT=$(objtree)/Documentation/output/rust/rustdoc
> Please add a space around the equal sign to be consistent with (most)
> of the rest of the file.


Ack


>
> Cheers,
> Miguel


Thanks,
Carlos