Windows API documentation for Rust

This is an experimental documentation generator for the Rust for Windows project. The documentation is published here:

https://microsoft.github.io/windows-docs-rs/

The modules crate generates the list of module paths to use in the bindings crate.

The bindings crate generates the documentation for the Windows API.

Unfortunately, the documentation cannot easily be published using GitHub Pages because GitHub has a 100MB limit on files and rustdoc generates a few files that are well over that limit. The build also cannot be automated with GitHub Actions as it takes around 30 minutes (mostly single-threaded) and will exhaust the CI build's resources (rustdoc allocates around 20GB of memory) and ultimately fails the build. A major reason for this is that cargo doc generates a multi-gigabyte windows.rs.html file containing the pretty-formatted version of the generated windows.rs file and there does not appear to be a way to exclude source code browsing using the Rust document generator.

It can be manually generated as follows:

C:\git\windows-docs-rs\crates\bindings>cargo doc --no-deps --target-dir ..\..\docs

You then need to be careful to delete any files that are over 100MB before pushing to GitHub.

You might also like...

Vibe - a library for acrylic/vibrancy effects for Electron on Windows 10/11

Comments

Adding Microsoft SECURITY.MD

Please accept this contribution adding the standard Microsoft SECURITY.MD :lock: file to help the community understand the security policy and how to safely report security issues. GitHub uses the presence of this file to light-up security reminders and a link to the file. This pull request commits the latest official SECURITY.MD file from https://github.com/microsoft/repo-templates/blob/main/shared/SECURITY.md.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

opened by microsoft-github-policy-service[bot] 0
Include `windows-rs` documentation in the generated docs

Following missing documentation in https://github.com/microsoft/windows-rs/issues/765.

None of the predefined types like Result, HRESULT or any other type in windows-rs are clickable links to the respective documentation. The --extern-html-root-url feature is still unstable but could otherwise be used to link to external documentation like docs.rs/windows.

EDIT: However, that will not make windows:: types searchable from windows-docs-rs since the types are still only linked externally. They are not part of the search index (afaik).

Note that by explicitly specifying what crates to document, both the windows and bindings crate have to be listed.

opened by MarijnS95 0