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

[Mark Hatle <mark.hatle@kernel.crashing.org>]

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)

--Mark

>      During a build, it can be necessary to perform operations that
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 41bda5d0d6..4e675b6bfb 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -4514,8 +4514,8 @@ system and gives an overview of their function and contents.
>   
>         The value in :term:`INITSCRIPT_PARAMS` is passed through to the
>         ``update-rc.d`` command. For more information on valid parameters,
> -      please see the ``update-rc.d`` manual page at
> -      https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html
> +      please see the ``update-rc.d`` manual page at :manpage:`update-rc.d
> +      <update-rc.d(8)>`.
>   
>      :term:`INSANE_SKIP`
>         Specifies the QA checks to skip for a specific package within a
> 
> 
> 
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#6647): https://lists.yoctoproject.org/g/docs/message/6647
> Mute This Topic: https://lists.yoctoproject.org/mt/111933087/3616948
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [mark.hatle@kernel.crashing.org]
> -=-=-=-=-=-=-=-=-=-=-=-
>