RFC: Website for Expanded Documentation

[akern40]

Summary

This RFC proposes the creation of a documentation website for ndarray using Material for MkDocs and an expansion of our documentation to include Explainers, Tutorials, and How-Tos. The website would be hosted via GitHub Pages. Code examples used in the documentation would be written in a snippets sub-crate and then automatically included in the docs, allowing us to test and prevent code-doc divergence or bit-rot. API documentation would always remain on docs.rs, although future website versions may also include API docs on the website for easier cross-referencing.

cc: @bluss @jturner314 @nilgoyette

Motivation

Now that #879 is resolved and the new array reference type is in, users will need to (re)learn how to write functions for ndarray. We could add an additional section to the ArrayBase documentation and call it a day. However, I think the library has outgrown our current documentation strategy, with the reference type being the canary in the coal mine.

Our current documentation strategy has limitations:

• We only capture a small amount of information about the library in any formal manner.
• Institutional knowledge is scattered across GitHub issues, discussions, and historical threads.
• Formal tutorials, explainers, and how-tos are sparse to nonexistent
• docs.rs is designed around API documentation, but not suited for the extended family of documentation needed for a complex project
• Keeping all of our documentation in comments puts a burden on maintainability, eliminating the ability to use syntax highlighting, hot reloading, or other features for keeping our documentation current and comprehensive

Lastly, a personal anecdote: I came to ndarray by way of trying to write Python NumPy acceleration libraries in Rust. I had to abandon the project for several reasons, but partially because I couldn't find the right library for it: nalgebra had fantastic documentation, a clean API, and it was blazing fast, but I needed stacks of covariance matrices, i.e., Nx3x3, and didn't want to use Vec<Matrix3>. It was clear that ndarray was the better pairing to NumPy, but I found the documentation really difficult to find and parse effectively. Like my work on the array reference type, this RFC is partially an attempt to provide my former self with the tools he would have needed to make the project a success.

Proposed Documentation Strategy

What to Document

Inspired by the Diátaxis framework, the website will provide three of Diátaxis's four kinds of documentation (the fourth, "Reference", is already covered by our docs.rs API documentation).

Note that a given topic (e.g., "writing functions") could show up in any or all three of these kinds, but how that information is presented and why it's being discussed are what distinguish each kind. See the Diátaxis framework website for an unsurprisingly well-documented overview.

Tutorials

Guided introductions for new users. For example: step-by-step walkthroughs, intermediate usage patterns, and introductions to new concepts.

Note that this is similar to "How-To Guides" but geared towards learning by doing, not towards practical applications.

How-To Guides

Practical solutions to specific problems. For example: performance optimization techniques, common tasks such as iteration, and solving specific challenges that users may run into.

Note that this is similar to an explainer, but geared towards solving a specific problem, not building the user's general conceptual knowledge.

Explanations

Conceptual and architectural insights. For example: deep dives into the library's types, the rationale behind panics, and other design choices.

Technical Implementation

I'd like to propose using Material for MkDocs. This approach offers several key advantages:

• A dedicated location for expanded documentation.
• Easy maintenance for Markdown-familiar contributors
• Ability to create structured, multi-page documentation
• Support for advanced features like syntax highlighting and cross-referencing
• Rich formatting capabilities beyond doc comments

In order to prevent bit-rot and code-docs drift, I'd also propose we create a snippets sub-crate that would host every snippet used in the documentation website. Material for MkDocs has a powerful and simple capability to paste in content from another file. This way, these snippets could have a single source of truth and be tested by our CI/CD.

Versioning

We can also employ mike for versioning our docs right along with our library.

Non-Goals

This documentation website would not:

• Teach Rust programming fundamentals to NumPy users
• Provide a comprehensive introduction to multidimensional arrays
• Replace the authoritative API documentation on docs.rs

The first two are huge undertakings for which excellent resources already exist. There is no need to reinvent the wheel. And API docs still belong on docs.rs, which remains an excellent tool for that use.

Challenges and Drawbacks

Here are the potential challenges and drawbacks of this approach:

• Balancing comprehensiveness with readability
• Risk of documentation becoming out of sync with code
• Introduction of Python into our website build
• Need for clear guidelines on documentation contributions
• Potential increased onboarding complexity for new contributors

On the Python note: we can keep things exceedingly simple by using uv in our CI/CD; the build command would be uvx --with mkdocs-material mkdocs build -d BUILD_TARGET

Rationale and Alternatives

Why This Approach?

• Markdown-Based Documentation
  • Familiar to Rust and open-source contributors
  • Easy to write and maintain
  • Version control friendly
• Material for MkDocs
  • Industry-standard documentation framework
  • Rich feature set
  • Excellent user experience
  • Minimal setup complexity
  • Open source
• Separate Documentation Site
  • Allows for more expansive explanations
  • Decouples documentation from code
  • Provides a dedicated space for institutional knowledge

Considered Alternatives

Just docs.rs

Keeping all documentation as comments forces maintainers to make a choice. Option one is to tie a given piece of documentation to a particular type, function, or module; but there's so much that deserves documenting that is not about one particular piece of code, and this approach seriously hurts discoverability.

Option two is to create an empty module that just consists of doc comments; but at that point, you're essentially creating a markdown website! But without any of the niceties of actually writing markdown or actually using a website. It seems to me to be the worst of both worlds.

GitHub Wiki

One approach that eliminates the additional infrastructure is using a GitHub wiki. But I think that the user experience will be noticeably worse, at a trade-off of a small amount of maintenance. This is mainly because its navigation capabilities aren't quite as good, nor are its various features like the snippets sub-crate idea.

Future Possibilities

When rust-lang/rust#76578 lands, we would be able to incorporate the API documentation directly into the external website. This could really open up the possibility for better cross-referencing.

Summary

As I stated at the beginning, I think users could really benefit from a centralized, intentional, and ergonomic documentation experience beyond what we have right now. I think this is a reasonable solution that adds minimal overhead while delivering a lot of value. I look forward to discussing it with our community. Thank you!

[akern40]

For an example of what this would look like, see this partial implementation on my fork.

[nilgoyette]

Excellent! Thank you for the write-up. I have some questions:

• Can we test locally? You already answered this in your partial implementation. I think this is important for people who know the internals less but still want to contribute.
• Can we reference (add links) content from the "other" site? Our doc contains a link to doc.rs, and doc.rs contains a link to our doc. Or this is currently a one-way?
• "Potential increased onboarding complexity for new contributors" Why? Because they must modify the code + doc in the same MR?

[NewBornRustacean]

what's up! as a newbie(a new contributor) to ndarray, it was really helpful for me to read materials like this PR: #1440 especially this kind of figure to understand structures/desgins and when/why to use each type.

                 ┌─────────┐                   
              ┌──┼ArrayBase│                   
              │  └────┬────┘                   
              │       │Deref when S: Data      
AsRef         │       │DerefMut when S: DataMut
when          │       │                        
S: RawData    │  ┌────▼────┐                   
              │  │ArrayRef ┼───────┐           
AsMut         │  └────┬────┘       │           
when          │       │Deref       │AsRef      
S: RawDataMut │       │DerefMut    │AsMut      
              │       │            │           
              │  ┌────▼────┐       │           
              ├──►RawRef   ◄───────┤           
              │  └────┬────┘       │           
        AsRef │       │ Deref      │AsRef      
        AsMut │       │ DerefMut   │AsMut      
              │       │            │           
              │  ┌────▼────┐       │           
              └──►LayoutRef◄───────┘           
                 └─────────┘                   

to me, this is about Explanation in the words of Diataxis.

Of course, as a new contributor, it's natural to spend some time reading through various issues in the repository to get familiar with the project. However, if this Explanation section exists somewhere in the documentation, it could save a lot of that time.

If possible, I think this Explanation section should include the following:

• A bird’s-eye view of the entire project
• Background on the design decisions made in the code
• Other explanations that can help with understanding the project

Introducing MkDocs for this purpose could create great synergy. Because to this end, we don't need to make live sync between codes and docs. If you're planning to use GitHub Pages, referring to the FAISS documentation might also be a good idea.

[akern40]

@nilgoyette good questions.

Can we test locally?

Yes, you can test the Rust snippets locally, you can always view the Markdown files with any viewer of your choice (e.g., the one built in to VSCode), and you can build the docs locally, including with a hot reload server where you can see your changes instantaneously.

Can we reference (add links) content from the "other" site?

We can link both way via hyperlinks. I think we can set up something simple to make sure that every link to docs.rs from the website will send you to the same version (i.e., if you're looking at the docs for 0.17.0 you'll get sent to docs.rs for 0.17.0). Doing that versioning in the other direction (docs.rs to the website) will probably have to be more manual. This is one point of developer burden.

"Potential increased onboarding complexity for new contributors" Why? Because they must modify the code + doc in the same MR?

That is part of it, ya. I was also thinking about the infrastructure to test the docs locally - it requires a Python setup, so we're asking our Rust devs to deal with Python environments. If it weren't for the recent dominance of uv and how incredibly simple it makes this, I would be hesitant. I made sure to include a website-specific README to handle this sort of information.