From 6ac27fa77ab8fcd79fc1787dc2ed467ac92a9526 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 6 Feb 2023 17:32:23 +0100 Subject: [PATCH 01/13] Create RFC for bundling local images in rustdoc output --- text/000-rustdoc-bundle-local-resources.md | 66 ++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 text/000-rustdoc-bundle-local-resources.md diff --git a/text/000-rustdoc-bundle-local-resources.md b/text/000-rustdoc-bundle-local-resources.md new file mode 100644 index 00000000000..34ae10257d5 --- /dev/null +++ b/text/000-rustdoc-bundle-local-resources.md @@ -0,0 +1,66 @@ +Rustdoc: Bundle local images + +- Feature Name: NONE +- Start Date: 2023-02-06 +- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) +- Rust Issue: [rust-lang/rust#32104](https://github.com/rust-lang/rust/issues/32104) + +# Summary +[summary]: #summary + +This RFC proposes to allow the bundling of local images in rustdoc HTML output. A draft implementation is available as [#107640](https://github.com/rust-lang/rust/pull/107640). + +# Motivation +[motivation]: #motivation + +Currently, rustdoc does not allow for the inclusion of local images in the generated output. This limits users from customizing their rustdoc output by adding images to their documentation as they currently need to host them on a web server so they can be available from anywhere, but therefore requiring an access to the internet. Bundling local images would enable users to customize their rustdoc output and make it more visually appealing. + +This would make the documentation more engaging and easier to understand while lowering the amount of effort required to achieve a better result. + +# Guide-level explanationvide +[guide-level-explanation]: #guide-level-explanation + +This RFC proposes to allow rustdoc to include local images in the generated documentation by copying them into the output directory. + +This would be done by allowing users to specify the path of a local resource file in doc comments. The resource file would be stored in the `local_resources/{crate name}` folder. The `local_resources` folder will be at the "top level" of the rustdoc output level (at the same level as the `static.files` or the `src` folders). + +The only local resources considered will be the ones in the markdown image syntax: `![resource title](path)`. + +The syntax for including a local resource file would be `{resource: }`, where `` is the path of the resource file relative to the source file. + +The path could be either a relative path (`../images/my_image.png`) or an absolute path (`/images/my_image.png`). + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +A new rustdoc pass will be added which would go through all documentation to gather local resources into a map. + +Then in HTML documentation generation, the local resources pathes will be replaced by their equivalent linking to the output directory instead. + +The local resources will be renamed depending on the order we go across them as follows: `{nb}{extension}`. The only thing kept is the original file extension. This solution was picked because it is possible for two local resources located in different folders to have the same filename, which would be problematic. + +You can look at what the implementation could look like in [#107640](https://github.com/rust-lang/rust/pull/107640). + +# Drawbacks +[drawbacks]: #drawbacks + +Allowing local resources in rustdoc output could lead to big output files if users include big resource files. This could lead to slower build times and increase the size of generated documentation (in particular in case of very big local resources!). + +# Prior art +[prior-art]: #prior-art + +- [sphinx](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-latex_additional_files) +- [haddock](https://haskell-haddock.readthedocs.io/en/latest/invoking.html?highlight=image#cmdoption-theme): it's mentioned in this command documentation that local files in the given directory will be copied into the generated output directory. +- [doxygen](https://doxygen.nl/manual/commands.html#cmdimage): supported through `\image`. + +# Rationale and alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +Currently, to provide resources, users need to specify external URLs for resources or inline them (if possible like the `svg` image format) directly into the documentation. It has the advantage to avoid the problem of large output files, but it also requires users to upload their resources to a web server to make them available everywhere. + +# Unresolved Questions +[unresolved-questions]: #unresolved-questions + +- Should we put a size limit on the local resources? +- Should we somehow keep the original local resource filename instead of just using a number instead? +- Should we use this feature for the logo if it's a local file? From b6e3a99103f6c9fea55d9ecf8c83ed9aaea35b90 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 6 Feb 2023 21:25:46 +0100 Subject: [PATCH 02/13] Clarifications and add more examples --- text/000-rustdoc-bundle-local-resources.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/text/000-rustdoc-bundle-local-resources.md b/text/000-rustdoc-bundle-local-resources.md index 34ae10257d5..d028ac19ad9 100644 --- a/text/000-rustdoc-bundle-local-resources.md +++ b/text/000-rustdoc-bundle-local-resources.md @@ -22,13 +22,19 @@ This would make the documentation more engaging and easier to understand while l This RFC proposes to allow rustdoc to include local images in the generated documentation by copying them into the output directory. -This would be done by allowing users to specify the path of a local resource file in doc comments. The resource file would be stored in the `local_resources/{crate name}` folder. The `local_resources` folder will be at the "top level" of the rustdoc output level (at the same level as the `static.files` or the `src` folders). +This would be done by allowing users to specify the path of a local resource file in doc comments. The resource file would be stored in the `local.resources/{crate name}` folder. The `local.resources` folder will be at the "top level" of the rustdoc output level (at the same level as the `static.files` or the `src` folders). -The only local resources considered will be the ones in the markdown image syntax: `![resource title](path)`. +The local resources files are also affected by the `--resource-suffix`. So if you use `ext` as resource suffix, all local resources filename will follow this pattern: `{name}-ext{extension}`. -The syntax for including a local resource file would be `{resource: }`, where `` is the path of the resource file relative to the source file. +The only local resources considered will be the ones in the markdown image syntax: `![resource title](path)`, where `` is the path of the resource file relative to the source file. -The path could be either a relative path (`../images/my_image.png`) or an absolute path (`/images/my_image.png`). +The path could be either a relative path (`../images/my_image.png`) or an absolute path (`/images/my_image.png`): + +```rust +/// Using a local image ![with absolute path](/local/image.png) +/// +/// Using a local image ![with relative path](../local/image.png) +``` # Reference-level explanation [reference-level-explanation]: #reference-level-explanation @@ -53,6 +59,10 @@ Allowing local resources in rustdoc output could lead to big output files if use - [haddock](https://haskell-haddock.readthedocs.io/en/latest/invoking.html?highlight=image#cmdoption-theme): it's mentioned in this command documentation that local files in the given directory will be copied into the generated output directory. - [doxygen](https://doxygen.nl/manual/commands.html#cmdimage): supported through `\image`. +Another approach to this feature: + +[ePUB packages](https://www.w3.org/publishing/epub3/epub-packages.html#sec-pkg-manifest) use explicitly-declared manifests. It allows to have a fallback chain mechanism (going through resources for an entry until an available resource is found). + # Rationale and alternatives [rationale-and-alternatives]: #rationale-and-alternatives From 864c222877c32355569cac6a748f2ea6538c2fcb Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 7 Feb 2023 21:58:28 +0100 Subject: [PATCH 03/13] Improve hash computation explanations and add new "Possible extensions" section --- text/000-rustdoc-bundle-local-resources.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/text/000-rustdoc-bundle-local-resources.md b/text/000-rustdoc-bundle-local-resources.md index d028ac19ad9..71ec8e128ba 100644 --- a/text/000-rustdoc-bundle-local-resources.md +++ b/text/000-rustdoc-bundle-local-resources.md @@ -24,8 +24,6 @@ This RFC proposes to allow rustdoc to include local images in the generated docu This would be done by allowing users to specify the path of a local resource file in doc comments. The resource file would be stored in the `local.resources/{crate name}` folder. The `local.resources` folder will be at the "top level" of the rustdoc output level (at the same level as the `static.files` or the `src` folders). -The local resources files are also affected by the `--resource-suffix`. So if you use `ext` as resource suffix, all local resources filename will follow this pattern: `{name}-ext{extension}`. - The only local resources considered will be the ones in the markdown image syntax: `![resource title](path)`, where `` is the path of the resource file relative to the source file. The path could be either a relative path (`../images/my_image.png`) or an absolute path (`/images/my_image.png`): @@ -36,6 +34,8 @@ The path could be either a relative path (`../images/my_image.png`) or an absolu /// Using a local image ![with relative path](../local/image.png) ``` +The local resources files are not affected by the `--resource-suffix`. + # Reference-level explanation [reference-level-explanation]: #reference-level-explanation @@ -43,7 +43,7 @@ A new rustdoc pass will be added which would go through all documentation to gat Then in HTML documentation generation, the local resources pathes will be replaced by their equivalent linking to the output directory instead. -The local resources will be renamed depending on the order we go across them as follows: `{nb}{extension}`. The only thing kept is the original file extension. This solution was picked because it is possible for two local resources located in different folders to have the same filename, which would be problematic. +The local resources files will be renamed as follows: `{original filename}-{hash}{extension}`. The `{hash}` information will be computed from the local resource file content. You can look at what the implementation could look like in [#107640](https://github.com/rust-lang/rust/pull/107640). @@ -74,3 +74,12 @@ Currently, to provide resources, users need to specify external URLs for resourc - Should we put a size limit on the local resources? - Should we somehow keep the original local resource filename instead of just using a number instead? - Should we use this feature for the logo if it's a local file? + +# Possible extensions +[possible-extensions]: #possible-extensions + +This feature could be extended to DOM content using local resources. It would require to add parsing for HTML tags attributes. For example: + +```html +///