pdoc VS mockttp

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

Interesting how the world has changed since the 2000s here - nowadays the ecosystem is far better, so it's much easier to set up tools to mess around with this, but the use of HTTPS everywhere makes it more difficult in more advanced cases (e.g. you'll often need to fight certificate configuration in individual clients).

In part because of that, browser extensions have become the main way to go for this kind of local web modification, but now there's new restrictions slowly coming in there too.

If you want to mess around with HTTP-level rewriting for yourself though, I maintain a Node.js library for easily writing tiny custom HTTP & HTTPS-intercepting proxies that makes it very easy: https://github.com/httptoolkit/mockttp/. Others have built more specific tooling on top too, like this web page modification proxy: https://github.com/OnkelTem/wmod-proxy

There's a walkthrough for setting up a quick local proxy & rewriting your own browser traffic here: https://httptoolkit.com/blog/javascript-mitm-proxy-mockttp/

> What did the first iteration of this product look like? Was it more or less similar, or substantially different from the spirit of httptoolkit today?

Technically, the first iteration was https://github.com/httptoolkit/mockttp - an HTTP integration testing library for JS. Not a desktop app at all. I'd originally built that for testing uses, but as it matured I realised that with a UI and automated setup tools it'd be useful as a complete product (but Mockttp still powers all the internals today, and you can use it directly to build your own custom intercepting proxies too).

For the first real product, the very first public 'launch' was literally a landing page with some demos of the potential UI and a signup form, just to test interest and check it wasn't a terrible idea. The results looked promising, so that was followed a few months later by a very basic but usable free version (entirely read-only, and only supporting Chrome interception) with the freemium features on top appearing a few months after that.

> How did you go from (some semblance of a product) to first sale? / acquiring first customer?

Once I announced the paid version (a blog post to my tiny set of newsletter signups, plus a little response on HN/Reddit/Product Hunt etc) I got a handful of paying customers (but certainly less than 10) within 24 hours. Nice but not a meaningful income, and from that wild peak it dropped back down to maybe one new customer per week or so afterwards, so it was quite slow going at the start.

However, those paying customers (and the mere fact of offering a paid service generally) resulted in _much_ better feedback. Rather than "this is cool" all of a sudden I had real demands for specific features, from people with concrete use cases and money in their hands. The initial paid features were just made up off the top of my head, and honestly didn't create a particularly compelling paid feature set. It's very hard to really know what people will pay for! That feedback was incredibly unbelievably useful to fix that.

From there, building out the key features people asked for over the following 6 months boosted things very significantly, and started to get things moving for real, and then you get into a virtuous circle, where more users => more feedback => better product => more users => ...

> did you spend anything on marketing/distribution?

I tested advertising at a small scale for a few months, but it didn't really work great. I think largely because it's very very freemium - 99% of users pay nothing - so the acquisition cost for a paying user doesn't make sense, and also honestly I don't have much experience with ads and I'm not sure I'm any good at writing them.

Content marketing meanwhile has worked great, keeps passively returning dividends, and cost nothing. I've tried to fill the blog (https://httptoolkit.com/blog/) exclusively with detailed & high-value original content (detailed breakdowns of a recent HTTP security vulnerability, not "top 10 HTTP libraries for Python") which shares well on social networks for an immediate burst of traffic, and then (in most cases) provides both a long-term SEO boost and constant incoming traffic on related topics that converts into users. That starts slow, but again steadily builds up over years, if you keep working at it. Content marketing + SEO are pretty much the only marketing channels I work on right now.

> why would I prefer this to mitmproxy?

Compared to mitmproxy, HTTP Toolkit:

- Has fully automated setup for most browsers, docker containers, Android, all Node.js/Ruby/Python/PHP/Go applications run from intercepted terminal windows, all JVM processes, any Electron apps etc etc. Some of these automated setup steps are very difficult to do manually (e.g. intercepting Android devices, where you can't normally install your own certificates nowadays, or intercepting Node.js, which completely ignores system proxy settings) so this can make a huge difference in non-trivial case.

- Supports targeted interception (intercept just one app/container/browser window) whilst all mitmproxy's manual setup steps are generally focused on helping you intercept your whole machine at once. Intercepting the whole machine means very noisy interception and means that rewriting traffic interferes with all other usage of your machine. Targeted interception means you can do neat things like run two HTTP Toolkit instances independently at the same time, and means you don't need root privileges or permanent configuration settings.

- Has generally friendlier UI & UX (imo). For example, mitmproxy uses a unique custom syntax (https://docs.mitmproxy.org/stable/concepts-filters/) of special characters to define matching & rewriting rules, or requires you to write a full python script. HTTP Toolkit lets you click 'new rule' -> 'GET requests' -> 'match regex ' -> 'then reply with ', and then immediately start injecting automated fake responses. From HTTP Toolkit you can then build named groups or these rules, and import & export them (as JSON) to build libraries you can share with your colleagues.

- Provides lots more background information automatically: e.g. built-in documentation for all standard HTTP headers, body autoformatting for lots more formats, syntax highlighting, code folding, regex searching etc of request & response bodies, plus 'this is how and why this response could be cached' caching explanations, OpenAPI-powered docs for recognized endpoints on 1400+ APIs, etc.

- Includes advanced features to do things like exporting requests as ready-to-use code for various languages & tools, or automatically testing the performance of different compression algorithms on a given response body.

- Is more easily scriptable for automation & end-to-end testing, because all the HTTP-handling internals are usable as a standalone open-source JS library: https://github.com/httptoolkit/mockttp

That said, mitmproxy has been around longer, it's definitely more mature, and it was a big inspiration in many places. It's a great project! It does have some advantages of its own:

- If you strongly prefer a CLI interface, mitmproxy is very focused on that, and HTTP Toolkit is not. HTTP Toolkit could support that too in theory (the backend & frontend are independent) but it definitely doesn't right now, and it's not high on my todo list (contributions welcome though!)

- Mitmproxy is primarily scriptable in Python. You can build automation around HTTP Toolkit's internals using mockttp, but that's JS, and it's mostly usable standalone right now, rather than integrated into normal workflows within the app. If you want very complex scripted rules, mitmproxy has a few more options right now, and lets you do things in python instead of JS, which some people will prefer.

- WebSocket debugging - this is coming for HTTP Toolkit soon, but it's not available today. WebSockets get passed through fine, but they don't appear in the UI, and you can't set up mock rules for them.

> I'd be interested both in why I'd prefer the open source httptoolkit and pro?

There's a list of Pro features at https://httptoolkit.tech/pricing/. Note that it's all open source, even the Pro code, everything.

The general idea is that everything you need to intercept, inspect and manually fiddle with traffic is totally free. Anything optional that most users don't need, but which is helpful for advanced usage or enterprise use cases, requires Pro.

HTTP Toolkit works on Windows, Mac and Linux. Head to https://httptoolkit.tech website and download the relevant package to install it.

I think MITM should provide a lot of features for that please checkout mock http https://github.com/httptoolkit/mockttp

Same with Telerik Fiddler recently. Good piece of software for debugging network requests on Windows.

Was free for as long as I've known it existed. Telerik recently bought by 'Progress' (ironic), software re-written in Electron and now charges a subscription to use it.

Glad HTTP Toolkit is now available free for most standard tasks - https://httptoolkit.tech/

HTTPToolKit has been my go-to for sniffing out packets from mobile apps in recent months.

I'd highly recommend https://httptoolkit.tech/ for that explorative GUI phase. I found it recently and the rule configuration, UI and interception setup is significantly better than Charles/Fiddler/Proxyman.

Do they want open source versions to get more popular? Because this is how you do that. HTTP TOOLKIT seems pretty decent, does anyone else have a recommendation?