pdoc VS Docusaurus

You can also use doc-strings to generate automated documentation for your code using a library like pdoc. Consider the following example from Stack-Scraper and the corresponding documentation generated using pdoc library.

I’ve used sphinx extensively and though it is one of the standards and does a ton, I do not like or recommend it. Personally, I realllly like pdoc for its simplicity. Do not confused pdoc with pdoc3

RE browser vs reading the code: sounds like you have a nicer setup than my neovim setup. Although I think my first point still holds unless CLion handles that case too.

With respect to the rest of your comment, indeed, those are issues. Although I think I take issue with you pinning this on rustdoc. I actually think it's a dance between documentation presentation (so, rustdoc), API design and familiarity with the language.

I've long said that rustdoc makes unknown unknowns difficult to discover, and this is particularly painful for folks new to Rust. Because you don't really know what to look for yet. And writing docs is a difficult exercise in perspective taking, where you need to balance what you think others know. If you assume they know too little, it's not hard to end up writing too much and adding a fair bit of noise. With that said, I agree that "too little docs" is a far more common problem than "too many docs."

But yeah, your experience is a perfect example of what I mean when I say "generics complicate APIs." They introduce indirection everywhere, and I'm not sure how much rustdoc can really help with that. You might be right that maybe there are some visualizations that can be added, but like you, I've always seen those as gimmicks in other tools that are rarely useful. IMO, a heavily generic API really requires the crate author to write more prose about how their APIs are intended to be used with lots of concrete examples.

The interesting bit here is that I've personally found the documentation experience in Rust to be far far better than any other ecosystem. All the way from writing docs up to consuming them. I've sampled many different ecosystems (C, C++, Haskell, Python, Go to name some) and other than maybe Go, I thought the doc experience was really just not great in any of them. Python specifically seems to be a case where I tend to see a lot of variance in opinion. I hated Sphinx so much, for example, that I built an alternative.[1] I also just generally dislike the output that Sphinx produces. I find that it lacks structure, and I've always had a hard time navigating my way through Python library docs.

[1]: https://github.com/mitmproxy/pdoc

Anyway, this is all my opinion. And a lot of it is based on reflecting on my own experience. I have no idea how well it generalizes. I have given this topic a lot of thought though, and have even written documentation generators for other ecosystems because I thought the other choices were bad enough to warrant spending a few weeks on such a tool.

Documentation is now generated using pdoc https://pdoc.dev. Thanks Dliwk!! (I'll get it wired up to auto-update to a webpage soon).

There's a comprehensive README.md with installation and Quickstart information on GitHub, and reference documentation (auto generated by pdoc) on GitHub Pages.

Our main docs are built with Hugo (https://github.com/mitmproxy/mitmproxy/tree/main/docs). For our API docs we use pdoc (https://pdoc.dev), which integrates well with most static site generators. pdoc is also maintained by us. :)

PEP 257 and a few others define "docstrings". Leverage them to make full use of autodoc tools. pdoc is a pretty fun tool that "just works". Build good habits from the start. Projects that have great documentation are just more attractive to me. If I come across a project that seems to do what I need, but has crappy documentation, I keep looking.

Hi HN! Some of you may remember @BurntSushi's pdoc tool, a lightweight alternative to Sphinx. We're a bit in an unfortunate situation with a hostile work assuming our name [1], but I figured that we shouldn't give in and continue the legacy of that tool. Long story short, we have just published a major new "modern Python 3" release, which hopefully makes pdoc a really compelling option again. :-)

[1] https://github.com/mitmproxy/pdoc#pdoc-vs-pdoc3

Docusaurus is a popular open-source documentation tool primarily designed for product documentation and other technical documentation needs. It was first released in 2017 by Facebook Open Source (now Meta Open Source). Just recently, Docsaurus version 3.0 was released.

// @ts-check // `@type` JSDoc annotations allow editor autocompletion and type checking // (when paired with `@ts-check`). // There are various equivalent ways to declare your Docusaurus config. // See: https://docusaurus.io/docs/api/docusaurus-config import { themes as prismThemes } from "prism-react-renderer"; /** @type {import('@docusaurus/types').Config} */ const config = { title: "My Site", tagline: "Dinosaurs are cool", url: "https://your-docusaurus-test-site.com", baseUrl: "/", onBrokenLinks: "throw", onBrokenMarkdownLinks: "warn", favicon: "img/favicon.ico", organizationName: "facebook", // Usually your GitHub org/user name. projectName: "docusaurus", // Usually your repo name. presets: [ [ "docusaurus-preset-openapi", /** @type {import('docusaurus-preset-openapi').Options} */ ({ docs: { sidebarPath: require.resolve("./sidebars.js"), // Please change this to your repo. editUrl: "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/", }, blog: { showReadingTime: true, // Please change this to your repo. editUrl: "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/", }, theme: { customCss: require.resolve("./src/css/custom.css"), }, }), ], ], themeConfig: /** @type {import('docusaurus-preset-openapi').ThemeConfig} */ ({ navbar: { title: "My Site", logo: { alt: "My Site Logo", src: "img/logo.svg", }, items: [ { type: "doc", docId: "intro", position: "left", label: "Tutorial", }, { to: "/api", label: "API", position: "left" }, { to: "/blog", label: "Blog", position: "left" }, { href: "https://github.com/facebook/docusaurus", label: "GitHub", position: "right", }, ], }, footer: { style: "dark", links: [ { title: "Docs", items: [ { label: "Tutorial", to: "/docs/intro", }, ], }, { title: "Community", items: [ { label: "Stack Overflow", href: "https://stackoverflow.com/questions/tagged/docusaurus", }, { label: "Discord", href: "https://discordapp.com/invite/docusaurus", }, { label: "Twitter", href: "https://twitter.com/docusaurus", }, ], }, { title: "More", items: [ { label: "Blog", to: "/blog", }, { label: "GitHub", href: "https://github.com/facebook/docusaurus", }, ], }, ], copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`, }, prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, }, }), }; export default config;

Facebook's React/Markdown SSG docusaurus does those things: https://docusaurus.io/

Though you may have to use a plugin for responsive images: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-id...

Docusaurus is an open-source static site generator built on React and has emerged as a popular tool for developing and maintaining product documentation. Its ease of use, extensive features, and robust community support make it a compelling choice for many organizations.

Wondering why Docusaurus (https://docusaurus.io) did not match their needs. Works perfectly fine as a blogging engine for our tech blog.

This is developed by Meta. You can create really nice-looking documentation websites super fast.

Docusaurus, a documentation tool by Facebook, hosts a showcase of other websites that use Docusaurus on their Homepage. The list of websites of this showcase is a typescript files that is maintained by Docusaurus devs, and that you can add your website to through PR: https://github.com/facebook/docusaurus/blob/main/website/src/data/users.tsx

Fix "Edit this page" links at the bottom of each doc (Problem with the Docusaurus build I guess)