Links between the user guide and the reference would be nice

[HadrienG2]

nalgebra provides two sources of documentation. The user guide is meant as a high-level description of the library, and is a lots more approachable when trying to discover its functionality, whereas the API documentation provides a more detailed reference suitable for answering more specific questions such as "why won't this code compile".

In this sense, these two forms of documentation are complementary. But currently, they don't link to one another. If I want to know more about a function described in the user guide, I need to manually look it up in the API documentation, through lots of copy and paste in the search box.

It would be nice if there were a way to automatically add links to the API reference in the user guide, so that one could just click on the name of the function in the user guide instead.

[milibopp]

This might be quite a bit of effort. And there is one crucial thing I cannot really find, namely the user guide's source code.

@sebcrozet where are you keeping that?

[HadrienG2]

Indeed, the amount of effort needed for this would depend on the toolchain used to generate the user guide. Since rustdoc uses a very regular scheme for reference documentation URLs, I would expect that starting from some sort of fully qualified name (e.g. "struct nalgebra::core::Matrix"), one could easily generate both user guide text ("Matrix") and an associated link to the reference documentation ("http://nalgebra.org/rustdoc/nalgebra/core/struct.Matrix.html"). But the toolchain used to build the user guide needs to be sufficiently flexible in order to allow all this markup generation to be easily integrated...

[sebcrozet]

The user guide is currently built with mkdocs. The source of the user guide is on the gh-pages branch of nalgebra (though I should move this to its own repo. in the future). Is guess there is some ways to add this kind of link with some custom Javascript.

[milibopp]

It would be nice if it could be done during generation of the static pages, as there is technically no need for client-side code for this kind of feature. Not sure how easy it is to do with mkdocs. Does it support some kind of templating?

[sebcrozet]

This issue has been moved to the nalgebra.org repository: dimforge/nalgebra.rs#9