Create RFC for bundling local images in rustdoc output #3

GuillaumeGomez · 2023-02-06T16:33:15Z

rendered

text/000-rustdoc-bundle-local-resources.md

…s" section

text/000-rustdoc-bundle-local-resources.md

* Add new entry for foreign items inlining. * Mention problem of packages size increase * Add unresolved questions about support for logo and favicon

…on this RFC * Change how cross-crate inlining will be handled

text/000-rustdoc-bundle-local-resources.md

notriddle · 2023-02-15T17:40:06Z

text/000-rustdoc-bundle-local-resources.md

+
+The only local resources considered will be the ones in the markdown image syntax: `![resource title](path)`, where `<path>` 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 (like `/home/user/project/images/my_image.png` or `C:/Users/user/project/images/my_image.png`) so that paths can be constructed using `OUT_DIR`:


After the confusion in Zulip, this probably needs to be a bit more explicit about the motivation here:

Suggested change

The path could be either a relative path (`../images/my_image.png`) or an absolute path (like `/home/user/project/images/my_image.png` or `C:/Users/user/project/images/my_image.png`) so that paths can be constructed using `OUT_DIR`:

The path could be any relative or absolute file path. For example, to include an image generated by [`build.rs`](https://doc.rust-lang.org/cargo/reference/build-scripts.html), concatenate a path with the `OUT_DIR` environment variable:

text/000-rustdoc-bundle-local-resources.md

notriddle · 2023-02-15T17:42:35Z

text/000-rustdoc-bundle-local-resources.md

+
+If the path isn't referring to a file, a warning will be emitted and rustdoc will left the path unchanged in the generated documentation.
+
+For published crates, <docs.rs> builds the contents of the `.crate` package in a sandbox with no internet access. Make sure any resources your docs need are [included](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) in the package.


Suggested change

For published crates, <docs.rs> builds the contents of the `.crate` package in a sandbox with no internet access. Make sure any resources your docs need are [included](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) in the package.

For published crates, [docs.rs] builds the contents of the `.crate` package in a sandbox with no internet access. Make sure any resources your docs need are [included](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) in the package.

notriddle · 2023-02-15T17:42:52Z

text/000-rustdoc-bundle-local-resources.md

+
+The local resources files are not affected by the `--resource-suffix`.
+
+The impact on >docs.rs> would also be very minimal as the size of a published crate resources is limited to a few megabytes. The only thing needed would be to handle the new `doc.files` folder.


Suggested change

The impact on >docs.rs> would also be very minimal as the size of a published crate resources is limited to a few megabytes. The only thing needed would be to handle the new `doc.files` folder.

The impact on [docs.rs] would also be very minimal as the size of a published crate resources is limited to a few megabytes. The only thing needed would be to handle the new `doc.files` folder.

text/000-rustdoc-bundle-local-resources.md

GuillaumeGomez · 2023-02-17T00:06:27Z

I fixed the links and added the explanation for cross-crate inlined images.

…ages

Create RFC for bundling local images in rustdoc output

6ac27fa

GuillaumeGomez force-pushed the rustdoc-bundle-local-images branch from 6af79df to 6ac27fa Compare February 6, 2023 16:44

notriddle reviewed Feb 6, 2023

View reviewed changes

GuillaumeGomez added 2 commits February 6, 2023 21:25

Clarifications and add more examples

b6e3a99

Improve hash computation explanations and add new "Possible extension…

864c222

…s" section

notriddle reviewed Feb 10, 2023

View reviewed changes

text/000-rustdoc-bundle-local-resources.md Outdated Show resolved Hide resolved

GuillaumeGomez added 2 commits February 10, 2023 19:01

Rename local.resources folder into doc.files

40b54df

Remove crate name from the local resources folder path

f9440f1

Nemo157 reviewed Feb 13, 2023

View reviewed changes

text/000-rustdoc-bundle-local-resources.md Outdated Show resolved Hide resolved

GuillaumeGomez added 3 commits February 13, 2023 18:16

Add information about what happen in case a file isn't found

4bfda8c

Explain better why both absolute and relative paths are necessary

088cc0c

Mention published packages

0d02c9f

notriddle reviewed Feb 13, 2023

View reviewed changes

text/000-rustdoc-bundle-local-resources.md Outdated Show resolved Hide resolved

jyn514 reviewed Feb 13, 2023

View reviewed changes

text/000-rustdoc-bundle-local-resources.md Show resolved Hide resolved

GuillaumeGomez added 3 commits February 13, 2023 23:09

Improve explanations for absolute paths in docs.rs

b0383eb

* Rewrite motivation section.

021c95f

* Add new entry for foreign items inlining. * Mention problem of packages size increase * Add unresolved questions about support for logo and favicon

* Mention that html_favicon_url and html_logo_url will also rely …

1f287b2

…on this RFC * Change how cross-crate inlining will be handled

notriddle reviewed Feb 15, 2023

View reviewed changes

text/000-rustdoc-bundle-local-resources.md Outdated Show resolved Hide resolved

notriddle reviewed Feb 15, 2023

View reviewed changes

Fix docs.rs appearance and add explanation for cross-crate inlined im…

b1203a5

…ages

GuillaumeGomez force-pushed the rustdoc-bundle-local-images branch from 8b0cdb8 to b1203a5 Compare February 17, 2023 00:06

Add missing backtick around "docs.rs"

c74baba

notriddle approved these changes Feb 23, 2023

View reviewed changes

GuillaumeGomez closed this Feb 27, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create RFC for bundling local images in rustdoc output #3

Create RFC for bundling local images in rustdoc output #3

GuillaumeGomez commented Feb 6, 2023 •

edited

Loading

notriddle Feb 15, 2023

notriddle Feb 15, 2023

notriddle Feb 15, 2023

GuillaumeGomez commented Feb 17, 2023


		The only local resources considered will be the ones in the markdown image syntax: `![resource title](path)`, where `<path>` 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 (like `/home/user/project/images/my_image.png` or `C:/Users/user/project/images/my_image.png`) so that paths can be constructed using `OUT_DIR`:

	The path could be either a relative path (`../images/my_image.png`) or an absolute path (like `/home/user/project/images/my_image.png` or `C:/Users/user/project/images/my_image.png`) so that paths can be constructed using `OUT_DIR`:
	The path could be any relative or absolute file path. For example, to include an image generated by [`build.rs`](https://doc.rust-lang.org/cargo/reference/build-scripts.html), concatenate a path with the `OUT_DIR` environment variable:


		If the path isn't referring to a file, a warning will be emitted and rustdoc will left the path unchanged in the generated documentation.

		For published crates, <docs.rs> builds the contents of the `.crate` package in a sandbox with no internet access. Make sure any resources your docs need are [included](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) in the package.

	For published crates, <docs.rs> builds the contents of the `.crate` package in a sandbox with no internet access. Make sure any resources your docs need are [included](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) in the package.
	For published crates, [docs.rs] builds the contents of the `.crate` package in a sandbox with no internet access. Make sure any resources your docs need are [included](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) in the package.


		The local resources files are not affected by the `--resource-suffix`.

		The impact on >docs.rs> would also be very minimal as the size of a published crate resources is limited to a few megabytes. The only thing needed would be to handle the new `doc.files` folder.

	The impact on >docs.rs> would also be very minimal as the size of a published crate resources is limited to a few megabytes. The only thing needed would be to handle the new `doc.files` folder.
	The impact on [docs.rs] would also be very minimal as the size of a published crate resources is limited to a few megabytes. The only thing needed would be to handle the new `doc.files` folder.

Create RFC for bundling local images in rustdoc output #3

Create RFC for bundling local images in rustdoc output #3

Conversation

GuillaumeGomez commented Feb 6, 2023 • edited Loading

notriddle Feb 15, 2023

Choose a reason for hiding this comment

notriddle Feb 15, 2023

Choose a reason for hiding this comment

notriddle Feb 15, 2023

Choose a reason for hiding this comment

GuillaumeGomez commented Feb 17, 2023

GuillaumeGomez commented Feb 6, 2023 •

edited

Loading