Re: [docs] [PATCH v3 1/6] documentation/conf.py: define a manpage url

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi Mark,

On Thu Mar 27, 2025 at 4:35 PM CET, Mark Hatle wrote:
> I'm going to be a bit pedantic below, I'm not sure it matters at this point but 
> I want to clarify one thing.
>
> On 3/27/25 4:07 AM, Antonin Godard via lists.yoctoproject.org wrote:
>> By defining the manpages_url we can use the :manpage: role in the
>> documentation for providing links to manpages. See:
>> https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url
>> 
>> Replace existing manpages links to use this role.
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/conf.py                      | 3 +++
>>   documentation/overview-manual/concepts.rst | 2 +-
>>   documentation/overview-manual/yp-intro.rst | 2 +-
>>   documentation/ref-manual/variables.rst     | 4 ++--
>>   4 files changed, 7 insertions(+), 4 deletions(-)
>> 
>> diff --git a/documentation/conf.py b/documentation/conf.py
>> index 477e75112a..0352bbef20 100644
>> --- a/documentation/conf.py
>> +++ b/documentation/conf.py
>> @@ -111,6 +111,9 @@ extlinks = {
>>       'wikipedia': ('https://en.wikipedia.org/wiki/%s', None),
>>   }
>>   
>> +# To able to use :manpage:`<something>` in the docs.
>> +manpages_url = 'https://manpages.debian.org/{path}'
>> +
>>   # Intersphinx config to use cross reference with BitBake user manual
>>   intersphinx_mapping = {
>>       'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None)
>> diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
>> index e4d806f98f..416c28f0d9 100644
>> --- a/documentation/overview-manual/concepts.rst
>> +++ b/documentation/overview-manual/concepts.rst
>> @@ -2204,7 +2204,7 @@ require root privileges, the fact that some earlier steps ran in a fake
>>   root environment does not cause problems.
>>   
>>   The capability to run tasks in a fake root environment is known as
>> -"`fakeroot <http://man.he.net/man1/fakeroot>`__", which is derived from
>> +":manpage:`fakeroot <fakeroot(1)>`", which is derived from
>>   the BitBake keyword/variable flag that requests a fake root environment
>>   for a task.
>>   
>> diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst
>> index 4a27e12e01..11e6d99e32 100644
>> --- a/documentation/overview-manual/yp-intro.rst
>> +++ b/documentation/overview-manual/yp-intro.rst
>> @@ -400,7 +400,7 @@ Yocto Project:
>>      Autobuilder :doc:`here </test-manual/understand-autobuilder>`.
>>   
>>   -  *Pseudo:* Pseudo is the Yocto Project implementation of
>> -   `fakeroot <http://man.he.net/man1/fakeroot>`__, which is used to run
>> +   :manpage:`fakeroot <fakeroot(1)>`, which is used to run
>>      commands in an environment that seemingly has root privileges.
>
>
> psuedo is an implementation of three separate items:
>
> fakeroot
> fakechroot
> fakepasswd (which was never a debian tool or widely used - it emulates 
> /etc/passwd and /etc/group that do not match the running system)

Thanks for the details. I will try clarifying that later in a separate patch.


Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com