[v3] docs: Integrate rustdoc into Rust documentation

[PATCH v3 2/2] docs: Integrate rustdoc generation into htmldocs

Posted by Carlos Bilbao 2 years, 9 months ago

Change target `make htmldocs` to combine RST Sphinx and the
generation of Rust documentation, when support is available.

Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
---
 Documentation/Makefile | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 64d44c1ecad3..f537cf558af6 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -92,6 +92,10 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 	fi
 
 htmldocs:
+# If Rust support is available, add rustdoc generated contents
+ifdef CONFIG_RUST
+	$(Q)$(MAKE) rustdoc
+endif
 	@$(srctree)/scripts/sphinx-pre-install --version-check
 	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
 
-- 
2.34.1

Re: [PATCH v3 2/2] docs: Integrate rustdoc generation into htmldocs

Posted by Akira Yokosawa 2 years, 9 months ago

On Tue, 6 Dec 2022 09:31:51 -0600, Carlos Bilbao wrote:
> Change target `make htmldocs` to combine RST Sphinx and the
> generation of Rust documentation, when support is available.
> 
> Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
> ---
>  Documentation/Makefile | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 64d44c1ecad3..f537cf558af6 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -92,6 +92,10 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>  	fi
>  
>  htmldocs:
> +# If Rust support is available, add rustdoc generated contents
> +ifdef CONFIG_RUST
> +	$(Q)$(MAKE) rustdoc
> +endif
>  	@$(srctree)/scripts/sphinx-pre-install --version-check
>  	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
>  

What about patch below on top of this?
This way, it is possible to skip rustdoc generation by saying:

    make CONFIG_RUST=n SPHINXDIRS=doc-guide htmldocs

The reordering is to complete Sphinx runs even if rustdoc generation
ends up in error.

With this applied on top,

Reviewed-by: Akira Yokosawa <akiyks@gmail.com>

        Thanks, Akira

------
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 2cf3e0fd7839..4d334468aaaf 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -92,12 +92,12 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
 	fi
 
 htmldocs:
+	@$(srctree)/scripts/sphinx-pre-install --version-check
+	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
 # If Rust support is available, add rustdoc generated contents
-ifdef CONFIG_RUST
+ifeq ($(CONFIG_RUST),y)
 	$(Q)$(MAKE) rustdoc
 endif
-	@$(srctree)/scripts/sphinx-pre-install --version-check
-	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
 
 texinfodocs:
 	@$(srctree)/scripts/sphinx-pre-install --version-check
--

Re: [PATCH v3 2/2] docs: Integrate rustdoc generation into htmldocs

Posted by Randy Dunlap 2 years, 9 months ago


On 12/6/22 15:11, Akira Yokosawa wrote:
> On Tue, 6 Dec 2022 09:31:51 -0600, Carlos Bilbao wrote:
>> Change target `make htmldocs` to combine RST Sphinx and the
>> generation of Rust documentation, when support is available.
>>
>> Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
>> ---
>>  Documentation/Makefile | 4 ++++
>>  1 file changed, 4 insertions(+)
>>
>> diff --git a/Documentation/Makefile b/Documentation/Makefile
>> index 64d44c1ecad3..f537cf558af6 100644
>> --- a/Documentation/Makefile
>> +++ b/Documentation/Makefile
>> @@ -92,6 +92,10 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>>  	fi
>>  
>>  htmldocs:
>> +# If Rust support is available, add rustdoc generated contents
>> +ifdef CONFIG_RUST
>> +	$(Q)$(MAKE) rustdoc
>> +endif
>>  	@$(srctree)/scripts/sphinx-pre-install --version-check
>>  	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
>>  
> 
> What about patch below on top of this?
> This way, it is possible to skip rustdoc generation by saying:
> 
>     make CONFIG_RUST=n SPHINXDIRS=doc-guide htmldocs
> 
> The reordering is to complete Sphinx runs even if rustdoc generation
> ends up in error.
> 
> With this applied on top,
> 
> Reviewed-by: Akira Yokosawa <akiyks@gmail.com>
> 
>         Thanks, Akira
> 

Oh yes, I like both of those changes.
Thanks.

> ------
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 2cf3e0fd7839..4d334468aaaf 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -92,12 +92,12 @@ quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>  	fi
>  
>  htmldocs:
> +	@$(srctree)/scripts/sphinx-pre-install --version-check
> +	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
>  # If Rust support is available, add rustdoc generated contents
> -ifdef CONFIG_RUST
> +ifeq ($(CONFIG_RUST),y)
>  	$(Q)$(MAKE) rustdoc
>  endif
> -	@$(srctree)/scripts/sphinx-pre-install --version-check
> -	@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
>  
>  texinfodocs:
>  	@$(srctree)/scripts/sphinx-pre-install --version-check

-- 
~Randy