Link to official examples from docs.rs documentation #1934
Comments
alice-i-cecile
added
C-Docs
|
Hi, I'm new to the code base and I don't have any experience contributing to open source but I want to start and offer my help. Would you be able to give me some pointers on how I can get familiar with the code base to tackle this issue? Should I start in the |
|
@hasanhaja sure, this is a great way to learn the code base! I'm also very active on Discord; feel free to say hi in #docs if you have quick questions. I think that working from the examples folder is going to be the most sensible approach here. Make a draft pull request, add a check-list for the examples and then methodically go through each of the examples and try to get at least one link in place for each example. As is typical in Rust, our documentation is built automatically from doc comments on the source code. You can find where that code might be by searching for it on Github or on docs.rs; just be mindful that you need to add the docs where the code is first defined, not where it's re-exported. We can help you write supporting documentation for any of the important concepts mentioned in those PRs if they're lacking / missing. In order to keep the review size small / the PRs merged quickly, I think one folder per PR is a pretty good chunk size :) |
I linked to examples within the rustdoc for the 2d examples as per issue #1934
|
Sorry for taking so long to get back to you, but I won't be able to work on this issue at the moment. |
I linked to examples within the rustdoc for the 2d examples as per issue bevyengine#1934
|
There's an exciting new nightly feature for this: https://twitter.com/wcrichton/status/1456112165744615426 ! |
Unfortunately that will produce dead links when e.g. some example is moved or renamed, because the link is not frozen to the version of the code it documents. I think this is understood and still the less worse solution, but just wanted to point it out explicitly. |
# Objective Working on issue #1934 , with linking examples to the documentation. PR for transform examples. ## Solution Added to the documentation in bevy_transform transform.rs and global_transform.rs utilizing links from examples. [X] 3d_rotations.rs linked to rotate in Transform [X] global_vs_local_translation.rs linked to top of Transform and GlobalTransform documentation [X] scale.rs linked to scale Struct in Transform [X] transform.rs linked to top of Transform documentation [X] translation.rs linked to from_translation in Transform Co-authored-by: bwhitt7 <103079612+bwhitt7@users.noreply.github.com>
# Objective Working on issue bevyengine#1934 , with linking examples to the documentation. PR for transform examples. ## Solution Added to the documentation in bevy_transform transform.rs and global_transform.rs utilizing links from examples. [X] 3d_rotations.rs linked to rotate in Transform [X] global_vs_local_translation.rs linked to top of Transform and GlobalTransform documentation [X] scale.rs linked to scale Struct in Transform [X] transform.rs linked to top of Transform documentation [X] translation.rs linked to from_translation in Transform Co-authored-by: bwhitt7 <103079612+bwhitt7@users.noreply.github.com>
# Objective Working on issue bevyengine#1934 , with linking examples to the documentation. PR for transform examples. ## Solution Added to the documentation in bevy_transform transform.rs and global_transform.rs utilizing links from examples. [X] 3d_rotations.rs linked to rotate in Transform [X] global_vs_local_translation.rs linked to top of Transform and GlobalTransform documentation [X] scale.rs linked to scale Struct in Transform [X] transform.rs linked to top of Transform documentation [X] translation.rs linked to from_translation in Transform Co-authored-by: bwhitt7 <103079612+bwhitt7@users.noreply.github.com>
# Objective Working on issue bevyengine#1934 , with linking examples to the documentation. PR for transform examples. ## Solution Added to the documentation in bevy_transform transform.rs and global_transform.rs utilizing links from examples. [X] 3d_rotations.rs linked to rotate in Transform [X] global_vs_local_translation.rs linked to top of Transform and GlobalTransform documentation [X] scale.rs linked to scale Struct in Transform [X] transform.rs linked to top of Transform documentation [X] translation.rs linked to from_translation in Transform Co-authored-by: bwhitt7 <103079612+bwhitt7@users.noreply.github.com>
|
done through example scrapping #9154 |
How can Bevy's documentation be improved?
Searching a term on docs.rs (or through your IDE's representation) is most user's first step when trying to understand how a function or struct work. For good reason, much of our documentation right now lives in the form of longer-form examples in the
examplesfolder of this repo.We should bridge this gap, by linking to these examples from the official documentation created through in-line comments.
Generally speaking, these links should live at the end of the doc-string comment, as they are most useful for readers who need more in-depth advice. Be sure to link to the
latestbranch of the examples, to avoid pointless churn on every release (or misleading examples when pointing tomain).Context
This was noticed in #1920. We will want better dead link detection (see #1579) to ensure that these links can stay fresh even if we move examples around.
The text was updated successfully, but these errors were encountered: