| Message ID | 20250327-cc-vars-v3-1-742dbddce008@bootlin.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Document missing toolchain related variables | expand |
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] > -=-=-=-=-=-=-=-=-=-=-=- >
Hi Antonin, On 3/27/25 10: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/%25s', None), > } > > +# To able to use :manpage:`<something>` in the docs. s/To able/To be able/ > +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. > > 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)>`. > This will render oddly no? I haven't compiled it but I assume something like """ please see the update-rc.d manual page at update-rc.d. """ ? If that's the case, maybe simply have: :manpage:`the update-rc.d manual page<update-rc.d(8)>`. ? What do you think? Please consider having a separate patch (not necessarily in this series) addressing Mark's feedback on fakeroot. Looks good to me otherwise, with some change for the update-rc.d paragraph: Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de> Thanks! Quentin
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
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. 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
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(-)