Generate rustdoc documentation with the rest of subsystem's documentation
in Documentation/output. Add a cross reference to the generated rustdoc in
Documentation/rust/index.rst.
Signed-off-by: Carlos Bilbao <[email protected]>
---
Documentation/rust/index.rst | 5 +++++
rust/Makefile | 15 +++++++++------
2 files changed, 14 insertions(+), 6 deletions(-)
diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
index 4ae8c66b94fa..416d6b3de1e4 100644
--- a/Documentation/rust/index.rst
+++ b/Documentation/rust/index.rst
@@ -6,6 +6,11 @@ Rust
Documentation related to Rust within the kernel. To start using Rust
in the kernel, please read the quick-start.rst guide.
+.. only:: html
+
+ If this documentation includes rustdoc-generated HTML, the entry
+ point can be found `here <rustdoc/kernel/index.html>`_.
+
.. toctree::
:maxdepth: 1
diff --git a/rust/Makefile b/rust/Makefile
index 7700d3853404..080c07048065 100644
--- a/rust/Makefile
+++ b/rust/Makefile
@@ -1,5 +1,8 @@
# SPDX-License-Identifier: GPL-2.0
+# Where to place rustdoc generated documentation
+RUSTDOC_OUTPUT = $(objtree)/Documentation/output/rust/rustdoc
+
always-$(CONFIG_RUST) += target.json
no-clean-files += target.json
@@ -58,7 +61,7 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
OBJTREE=$(abspath $(objtree)) \
$(RUSTDOC) $(if $(rustdoc_host),$(rust_common_flags),$(rust_flags)) \
$(rustc_target_flags) -L$(objtree)/$(obj) \
- --output $(objtree)/$(obj)/doc \
+ --output $(RUSTDOC_OUTPUT) \
--crate-name $(subst rustdoc-,,$@) \
@$(objtree)/include/generated/rustc_cfg $<
@@ -75,15 +78,15 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
# and then retouch the generated files.
rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
rustdoc-alloc rustdoc-kernel
- $(Q)cp $(srctree)/Documentation/images/logo.svg $(objtree)/$(obj)/doc
- $(Q)cp $(srctree)/Documentation/images/COPYING-logo $(objtree)/$(obj)/doc
- $(Q)find $(objtree)/$(obj)/doc -name '*.html' -type f -print0 | xargs -0 sed -Ei \
+ $(Q)cp $(srctree)/Documentation/images/logo.svg $(RUSTDOC_OUTPUT)
+ $(Q)cp $(srctree)/Documentation/images/COPYING-logo $(RUSTDOC_OUTPUT)
+ $(Q)find $(RUSTDOC_OUTPUT) -name '*.html' -type f -print0 | xargs -0 sed -Ei \
-e 's:rust-logo\.svg:logo.svg:g' \
-e 's:rust-logo\.png:logo.svg:g' \
-e 's:favicon\.svg:logo.svg:g' \
-e 's:<link rel="alternate icon" type="image/png" href="[./]*favicon-(16x16|32x32)\.png">::g'
$(Q)echo '.logo-container > img { object-fit: contain; }' \
- >> $(objtree)/$(obj)/doc/rustdoc.css
+ >> $(RUSTDOC_OUTPUT)/rustdoc.css
rustdoc-macros: private rustdoc_host = yes
rustdoc-macros: private rustc_target_flags = --crate-type proc-macro \
@@ -141,7 +144,7 @@ quiet_cmd_rustdoc_test = RUSTDOC T $<
@$(objtree)/include/generated/rustc_cfg \
$(rustc_target_flags) $(rustdoc_test_target_flags) \
--sysroot $(objtree)/$(obj)/test/sysroot $(rustdoc_test_quiet) \
- -L$(objtree)/$(obj)/test --output $(objtree)/$(obj)/doc \
+ -L$(objtree)/$(obj)/test --output $(RUSTDOC_OUTPUT) \
--crate-name $(subst rusttest-,,$@) $<
# We cannot use `-Zpanic-abort-tests` because some tests are dynamic,
--
2.34.1
On Tue, 6 Dec 2022 09:31:50 -0600, Carlos Bilbao wrote:
> Generate rustdoc documentation with the rest of subsystem's documentation
> in Documentation/output. Add a cross reference to the generated rustdoc in
> Documentation/rust/index.rst.
>
> Signed-off-by: Carlos Bilbao <[email protected]>
Reviewed-by: Akira Yokosawa <[email protected]>
> ---
> Documentation/rust/index.rst | 5 +++++
> rust/Makefile | 15 +++++++++------
> 2 files changed, 14 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
> index 4ae8c66b94fa..416d6b3de1e4 100644
> --- a/Documentation/rust/index.rst
> +++ b/Documentation/rust/index.rst
> @@ -6,6 +6,11 @@ Rust
> Documentation related to Rust within the kernel. To start using Rust
> in the kernel, please read the quick-start.rst guide.
>
> +.. only:: html
> +
> + If this documentation includes rustdoc-generated HTML, the entry
> + point can be found `here <rustdoc/kernel/index.html>`_.
> +
> .. toctree::
> :maxdepth: 1
>
> diff --git a/rust/Makefile b/rust/Makefile
> index 7700d3853404..080c07048065 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -1,5 +1,8 @@
> # SPDX-License-Identifier: GPL-2.0
>
> +# Where to place rustdoc generated documentation
> +RUSTDOC_OUTPUT = $(objtree)/Documentation/output/rust/rustdoc
> +
> always-$(CONFIG_RUST) += target.json
> no-clean-files += target.json
>
> @@ -58,7 +61,7 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
> OBJTREE=$(abspath $(objtree)) \
> $(RUSTDOC) $(if $(rustdoc_host),$(rust_common_flags),$(rust_flags)) \
> $(rustc_target_flags) -L$(objtree)/$(obj) \
> - --output $(objtree)/$(obj)/doc \
> + --output $(RUSTDOC_OUTPUT) \
> --crate-name $(subst rustdoc-,,$@) \
> @$(objtree)/include/generated/rustc_cfg $<
>
> @@ -75,15 +78,15 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
> # and then retouch the generated files.
> rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
> rustdoc-alloc rustdoc-kernel
> - $(Q)cp $(srctree)/Documentation/images/logo.svg $(objtree)/$(obj)/doc
> - $(Q)cp $(srctree)/Documentation/images/COPYING-logo $(objtree)/$(obj)/doc
> - $(Q)find $(objtree)/$(obj)/doc -name '*.html' -type f -print0 | xargs -0 sed -Ei \
> + $(Q)cp $(srctree)/Documentation/images/logo.svg $(RUSTDOC_OUTPUT)
> + $(Q)cp $(srctree)/Documentation/images/COPYING-logo $(RUSTDOC_OUTPUT)
> + $(Q)find $(RUSTDOC_OUTPUT) -name '*.html' -type f -print0 | xargs -0 sed -Ei \
> -e 's:rust-logo\.svg:logo.svg:g' \
> -e 's:rust-logo\.png:logo.svg:g' \
> -e 's:favicon\.svg:logo.svg:g' \
> -e 's:<link rel="alternate icon" type="image/png" href="[./]*favicon-(16x16|32x32)\.png">::g'
> $(Q)echo '.logo-container > img { object-fit: contain; }' \
> - >> $(objtree)/$(obj)/doc/rustdoc.css
> + >> $(RUSTDOC_OUTPUT)/rustdoc.css
>
> rustdoc-macros: private rustdoc_host = yes
> rustdoc-macros: private rustc_target_flags = --crate-type proc-macro \
> @@ -141,7 +144,7 @@ quiet_cmd_rustdoc_test = RUSTDOC T $<
> @$(objtree)/include/generated/rustc_cfg \
> $(rustc_target_flags) $(rustdoc_test_target_flags) \
> --sysroot $(objtree)/$(obj)/test/sysroot $(rustdoc_test_quiet) \
> - -L$(objtree)/$(obj)/test --output $(objtree)/$(obj)/doc \
> + -L$(objtree)/$(obj)/test --output $(RUSTDOC_OUTPUT) \
> --crate-name $(subst rusttest-,,$@) $<
>
> # We cannot use `-Zpanic-abort-tests` because some tests are dynamic,
On Tue, 06 Dec 2022, Carlos Bilbao <[email protected]> wrote:
> Generate rustdoc documentation with the rest of subsystem's documentation
> in Documentation/output. Add a cross reference to the generated rustdoc in
> Documentation/rust/index.rst.
>
> Signed-off-by: Carlos Bilbao <[email protected]>
> ---
> Documentation/rust/index.rst | 5 +++++
> rust/Makefile | 15 +++++++++------
> 2 files changed, 14 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
> index 4ae8c66b94fa..416d6b3de1e4 100644
> --- a/Documentation/rust/index.rst
> +++ b/Documentation/rust/index.rst
> @@ -6,6 +6,11 @@ Rust
> Documentation related to Rust within the kernel. To start using Rust
> in the kernel, please read the quick-start.rst guide.
>
> +.. only:: html
> +
> + If this documentation includes rustdoc-generated HTML, the entry
> + point can be found `here <rustdoc/kernel/index.html>`_.
> +
It's a bit meh to have documentation that points to places that might
404 and the user has to figure it out.
We can do better than that.
You could use CONFIG_RUST to pass e.g. "-t rustdoc" to Sphinx in the
Makefile, and use:
.. only:: rustdoc
and
.. only:: not rustdoc
And document accordingly.
Also, please don't use "here" as the link text.
BR,
Jani.
> .. toctree::
> :maxdepth: 1
>
> diff --git a/rust/Makefile b/rust/Makefile
> index 7700d3853404..080c07048065 100644
> --- a/rust/Makefile
> +++ b/rust/Makefile
> @@ -1,5 +1,8 @@
> # SPDX-License-Identifier: GPL-2.0
>
> +# Where to place rustdoc generated documentation
> +RUSTDOC_OUTPUT = $(objtree)/Documentation/output/rust/rustdoc
> +
> always-$(CONFIG_RUST) += target.json
> no-clean-files += target.json
>
> @@ -58,7 +61,7 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
> OBJTREE=$(abspath $(objtree)) \
> $(RUSTDOC) $(if $(rustdoc_host),$(rust_common_flags),$(rust_flags)) \
> $(rustc_target_flags) -L$(objtree)/$(obj) \
> - --output $(objtree)/$(obj)/doc \
> + --output $(RUSTDOC_OUTPUT) \
> --crate-name $(subst rustdoc-,,$@) \
> @$(objtree)/include/generated/rustc_cfg $<
>
> @@ -75,15 +78,15 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
> # and then retouch the generated files.
> rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
> rustdoc-alloc rustdoc-kernel
> - $(Q)cp $(srctree)/Documentation/images/logo.svg $(objtree)/$(obj)/doc
> - $(Q)cp $(srctree)/Documentation/images/COPYING-logo $(objtree)/$(obj)/doc
> - $(Q)find $(objtree)/$(obj)/doc -name '*.html' -type f -print0 | xargs -0 sed -Ei \
> + $(Q)cp $(srctree)/Documentation/images/logo.svg $(RUSTDOC_OUTPUT)
> + $(Q)cp $(srctree)/Documentation/images/COPYING-logo $(RUSTDOC_OUTPUT)
> + $(Q)find $(RUSTDOC_OUTPUT) -name '*.html' -type f -print0 | xargs -0 sed -Ei \
> -e 's:rust-logo\.svg:logo.svg:g' \
> -e 's:rust-logo\.png:logo.svg:g' \
> -e 's:favicon\.svg:logo.svg:g' \
> -e 's:<link rel="alternate icon" type="image/png" href="[./]*favicon-(16x16|32x32)\.png">::g'
> $(Q)echo '.logo-container > img { object-fit: contain; }' \
> - >> $(objtree)/$(obj)/doc/rustdoc.css
> + >> $(RUSTDOC_OUTPUT)/rustdoc.css
>
> rustdoc-macros: private rustdoc_host = yes
> rustdoc-macros: private rustc_target_flags = --crate-type proc-macro \
> @@ -141,7 +144,7 @@ quiet_cmd_rustdoc_test = RUSTDOC T $<
> @$(objtree)/include/generated/rustc_cfg \
> $(rustc_target_flags) $(rustdoc_test_target_flags) \
> --sysroot $(objtree)/$(obj)/test/sysroot $(rustdoc_test_quiet) \
> - -L$(objtree)/$(obj)/test --output $(objtree)/$(obj)/doc \
> + -L$(objtree)/$(obj)/test --output $(RUSTDOC_OUTPUT) \
> --crate-name $(subst rusttest-,,$@) $<
>
> # We cannot use `-Zpanic-abort-tests` because some tests are dynamic,
--
Jani Nikula, Intel Open Source Graphics Center
On 12/7/22 2:27 AM, Jani Nikula wrote:
> On Tue, 06 Dec 2022, Carlos Bilbao <[email protected]> wrote:
>> Generate rustdoc documentation with the rest of subsystem's documentation
>> in Documentation/output. Add a cross reference to the generated rustdoc in
>> Documentation/rust/index.rst.
>>
>> Signed-off-by: Carlos Bilbao <[email protected]>
>> ---
>> Documentation/rust/index.rst | 5 +++++
>> rust/Makefile | 15 +++++++++------
>> 2 files changed, 14 insertions(+), 6 deletions(-)
>>
>> diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
>> index 4ae8c66b94fa..416d6b3de1e4 100644
>> --- a/Documentation/rust/index.rst
>> +++ b/Documentation/rust/index.rst
>> @@ -6,6 +6,11 @@ Rust
>> Documentation related to Rust within the kernel. To start using Rust
>> in the kernel, please read the quick-start.rst guide.
>>
>> +.. only:: html
>> +
>> + If this documentation includes rustdoc-generated HTML, the entry
>> + point can be found `here <rustdoc/kernel/index.html>`_.
>> +
>
> It's a bit meh to have documentation that points to places that might
> 404 and the user has to figure it out.
>
> We can do better than that.
>
> You could use CONFIG_RUST to pass e.g. "-t rustdoc" to Sphinx in the
> Makefile, and use:
>
> .. only:: rustdoc
>
> and
>
> .. only:: not rustdoc
>
> And document accordingly.
>
> Also, please don't use "here" as the link text.
Why not?
>
> BR,
> Jani.
>
>
>> .. toctree::
>> :maxdepth: 1
>>
>> diff --git a/rust/Makefile b/rust/Makefile
>> index 7700d3853404..080c07048065 100644
>> --- a/rust/Makefile
>> +++ b/rust/Makefile
>> @@ -1,5 +1,8 @@
>> # SPDX-License-Identifier: GPL-2.0
>>
>> +# Where to place rustdoc generated documentation
>> +RUSTDOC_OUTPUT = $(objtree)/Documentation/output/rust/rustdoc
>> +
>> always-$(CONFIG_RUST) += target.json
>> no-clean-files += target.json
>>
>> @@ -58,7 +61,7 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
>> OBJTREE=$(abspath $(objtree)) \
>> $(RUSTDOC) $(if $(rustdoc_host),$(rust_common_flags),$(rust_flags)) \
>> $(rustc_target_flags) -L$(objtree)/$(obj) \
>> - --output $(objtree)/$(obj)/doc \
>> + --output $(RUSTDOC_OUTPUT) \
>> --crate-name $(subst rustdoc-,,$@) \
>> @$(objtree)/include/generated/rustc_cfg $<
>>
>> @@ -75,15 +78,15 @@ quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<
>> # and then retouch the generated files.
>> rustdoc: rustdoc-core rustdoc-macros rustdoc-compiler_builtins \
>> rustdoc-alloc rustdoc-kernel
>> - $(Q)cp $(srctree)/Documentation/images/logo.svg $(objtree)/$(obj)/doc
>> - $(Q)cp $(srctree)/Documentation/images/COPYING-logo $(objtree)/$(obj)/doc
>> - $(Q)find $(objtree)/$(obj)/doc -name '*.html' -type f -print0 | xargs -0 sed -Ei \
>> + $(Q)cp $(srctree)/Documentation/images/logo.svg $(RUSTDOC_OUTPUT)
>> + $(Q)cp $(srctree)/Documentation/images/COPYING-logo $(RUSTDOC_OUTPUT)
>> + $(Q)find $(RUSTDOC_OUTPUT) -name '*.html' -type f -print0 | xargs -0 sed -Ei \
>> -e 's:rust-logo\.svg:logo.svg:g' \
>> -e 's:rust-logo\.png:logo.svg:g' \
>> -e 's:favicon\.svg:logo.svg:g' \
>> -e 's:<link rel="alternate icon" type="image/png" href="[./]*favicon-(16x16|32x32)\.png">::g'
>> $(Q)echo '.logo-container > img { object-fit: contain; }' \
>> - >> $(objtree)/$(obj)/doc/rustdoc.css
>> + >> $(RUSTDOC_OUTPUT)/rustdoc.css
>>
>> rustdoc-macros: private rustdoc_host = yes
>> rustdoc-macros: private rustc_target_flags = --crate-type proc-macro \
>> @@ -141,7 +144,7 @@ quiet_cmd_rustdoc_test = RUSTDOC T $<
>> @$(objtree)/include/generated/rustc_cfg \
>> $(rustc_target_flags) $(rustdoc_test_target_flags) \
>> --sysroot $(objtree)/$(obj)/test/sysroot $(rustdoc_test_quiet) \
>> - -L$(objtree)/$(obj)/test --output $(objtree)/$(obj)/doc \
>> + -L$(objtree)/$(obj)/test --output $(RUSTDOC_OUTPUT) \
>> --crate-name $(subst rusttest-,,$@) $<
>>
>> # We cannot use `-Zpanic-abort-tests` because some tests are dynamic,
>
Thanks,
Carlos
On Wed, 07 Dec 2022, Carlos Bilbao <[email protected]> wrote:
> On 12/7/22 2:27 AM, Jani Nikula wrote:
>> Also, please don't use "here" as the link text.
>
> Why not?
It's considered bad style, see e.g. [1] or [2] or the plethora of
results you get if you search for "here as the link text".
The link text should describe what's at the destination.
BR,
Jani.
[1] https://ux.stackexchange.com/questions/12100/why-shouldnt-we-use-words-such-as-here-and-this-in-textlinks
[2] https://www.w3.org/QA/Tips/noClickHere
--
Jani Nikula, Intel Open Source Graphics Center
On 12/7/22 08:15, Jani Nikula wrote:
> On Wed, 07 Dec 2022, Carlos Bilbao <[email protected]> wrote:
>> On 12/7/22 2:27 AM, Jani Nikula wrote:
>>> Also, please don't use "here" as the link text.
>> Why not?
> It's considered bad style, see e.g. [1] or [2] or the plethora of
> results you get if you search for "here as the link text".
>
> The link text should describe what's at the destination.
Understood, thanks!
>
> BR,
> Jani.
>
>
> [1] https://ux.stackexchange.com/questions/12100/why-shouldnt-we-use-words-such-as-here-and-this-in-textlinks
> [2] https://www.w3.org/QA/Tips/noClickHere
>
>
Best regards,
Carlos
Carlos Bilbao <[email protected]> writes:
> On 12/7/22 2:27 AM, Jani Nikula wrote:
>> Also, please don't use "here" as the link text.
>
> Why not?
Among other things, that makes things harder for people using screen
readers and other assistive technology.
Thanks,
jon