Nice. The dependency of Qt WebEngine (i.e. Chromium) is a bit unfortunate (size, complexity); sure QTextDocument/QTextLayout/QTextHtmlParser/QCssParser is not sufficient enough for this?
the equivalent on macOS was to use Dictionary, but I suspect that it not really viable anymore due to format/rendering contraints: CHM probably needed IE6 like compatibility, after looking for docs, Dictionary needs XHTML, which might easily cool any enthusiasm
I wish it had a proper installable app. Relying on browser local storage is a nightmare since your browser will randomly and with no warning delete it all. The whole point of offline docs is that they're available... offline. On more than one occasion I've gone back to devdocs.io and everything I saved locally is wiped out, and of course I'm offline and just can't do anything.
Give me local HTML files I can stash in my filesystem. I actually just use wget to recursively archive entire documentation sites to local folders and serve them up with python's built in web browser. It's the only way to be sure I have accurate and up to date offline docs.
Give me local HTML files I can stash in my filesystem.
Apparently devdocs does have an API to download docsets. I just installed the Emacs package that someone recommended in another thread and it let me download the docs.
Sign me onto this same worry. It only takes one incident of offline mode borking to get upset.
Since the devdocs representation is so standardized, I have wondered if I could dump their database into SQLite and browse it with datasette. Should even be able to maintain text searching.
Is the Zeal code open source enough that one could change the backend by replacing a small number of data access subroutines?
I think all you would need to change is setter code, since getter code wouldn’t be part of the interface. I think Zeal doesn’t write back any data, right ?
Not experienced with Zeal, but I have used devdocs, which is open source. Devdocs parses the relevant documentation pages and stores them in a more structured way inside a browser database file. I would prefer to keep that in a local SQLite file I fully control. However, storing the data is not enough, I need an easy way to search and browse the documentation. Datasette is a Python project which spawns a web interface to a SQLite database which gives an interactive way to explore the data. This interface should be sufficient for locally hosting and searching the documentation.
I love devdocs.io when it works, but almost every other time I open it, it has forgotten my documentation configuration and I have to start from scratch. I don't have problems losing cookies, etc., elsewhere. And I have a peeve with it asking me to reload the page over and over and over, and each time I do it loses my place. It's a great source otherwise.
Happy user here - Zeal (and Dash on MacOS) is an easy productivity win, even if you're online (Django online docs search is notoriously bad for some reason), and indispensable if on a spotty connection or offline.
I still use dash 4. The newer versions removed the explorer tree and I don’t see any way to get it back. I feel like they make newer, worse versions, for the sake of selling upgrade licenses.
I wish this approach were more supported by those producing documentation. Looking things up in reference docs is one of those cases where reducing friction yields huge productivity benefits, but I still end up using a search engine (Kagi now as Google hides authoritative reference docs under a pile of poor-quality, irrelevant spam these days). I've tried Zeal multiple times but while the app is nice and many of the docsets are good, many of them aren't good: badly formatted, badly indexed, outdated or simply nonexistent. A search engine requires no setup and covers everything. It's just so horribly slow.
If we were grown ups, all software authors/vendors would be providing their reference docs in a standardised form, findable, downloadable and displayable by a wide range of tooling, consistent across languages, IDEs and platforms. Zeal is the closest we have, and it's a noble effort, but IME it doesn't solve the problem well enough to be useful because there's no buy-in from the people producing the docs.
(First to mention ChatGPT gets slapped with a wet fish. Just try me.)
In hope I avoid getting slapped with a wet fish, I would love to see a future version of Zeal with an option to ingest the docsets into a vector database and "chat" with it using a (local) LLM that's fine tuned for answering technical docs questions.
To stay on topic, I feel the pain: Zeal is so nice I curse when I need to look up something in the docs that aren't supported (Django REST Framework, in my case), since they use a different doc framework and can't be easily prepared for Dash/Zeal.
Somewhat related: wonder if using a local LLM could make it more feasible to federate reference documentation by translating various doc formats into a common one.
And on the other side of things, there's a growing trend in the Python library ecosystem of simply not writing reference documentation at all, instead providing either a few or a lot of user guides and tutorials, and directing users to either read those and try to interpret their mysteries, or expecting users to read the source code and interpret those mysteries. It makes no sense to me. The Pydantic issue tracker for example is absolutely full of people simply trying to figure out how to use the damn thing.
Glad you picked on pydantic. There is no reference doc whatsoever. The expectation is that you are supposed to learn by reading examples!
Back in the days of yore, software engineering teams led by greybeards used to be conservative in what dependencies they import into the projects. Those days are gone! Everyone imports everything today without any discerning eye.
> Those days are gone! Everyone imports everything today without any discerning eye.
That's even considered a feature today! If you don't have a language package manager that allows you to transparently import tons of stuff you've never heard of, then the language is considered crap.
Yeah, I was struggling with this trend earlier when looking at the Textual library, which has amazing examples but doesn't seem to have very detailed full API documentation.
I wonder why this trend is happening, especially when python in particular has a bunch of standards and tools to make generating full API docs pretty straightforward.
I think it's partly because Sphinx is clunky and people have been using MkDocs instead, which I believe either doesn't generate anything from docstrings at all, or didn't until recently. I don't know why they're not using Pdoc, maybe they don't know about it.
I also get the sense that there is a growing movement among programmers that API reference documentation is useless, or not worth putting effort into, because it's possible to go out of sync with the code and "nobody reads that anyway". I've heard people say things like "if you're advanced enough to read reference documentation, you're better off just reading the source anyway." It seems to be rooted in some kind of combination of extreme cynicism, a distorted sense of how people who aren't raw beginners learn to do things, and of a kind of false minimalism, wherein API documentation is old fuddy-duddy stuff for Java and C++ developers, and the new friendly easy way is to just read the examples. Such libraries also seem to exhibit a poor separation of public and private interfaces, so maybe it's just a reflection of people being bad at designing libraries.
I think what you've said feels exactly right. Maybe a better Sphinx just needs to exist, it seems like pythons standards should make it pretty simple to write something where API documentation generation is so trivial there's no reason not to.
I normally do end up reading source code, but it often introduces unnecessary hassle because while it's great for "what does this function do?" type of stuff, it really falls down when you want to know "what type of functions fall under this module" since you end up navigating up and down through a lot of imports that make sense for code organization but are abstracted away at the point of use.
I miss the documentation that was part of Microsoft MSDN subscription. I now work in a sandboxed environment and cannot access help for the APIs from within that environment so something that I can download in it's entirety and get into that environment would be ideal.
I'm a technical writer. I have felt this a lot myself. It is very comforting to know that the man pages are always there if I need them. Same with the Rust docs. And Beej's Guide to C Programming (I downloaded the PDF). Conversely, it kinda sucks to have to rely on a website to get info. I will kick off a discussion around offline docs in the technical writer communities that I'm part of.
Dash is a commercial software on macOS. The author created the whole docset parsing/plugin stuff and markets the tool. I use it for years and upgraded multiple times since it’s a timesaver.
There has been controversy in the past about the tool since it is a glorified man page reader. The author even shared at one point his earnings and what he is doing with it.
And no there is no zeal for macOS. I don’t know the details behind that deal. I can only say that zeal is not as good as dash. The integration into macOS is way smoother than what one gets on windows and Linux. I tried all versions.
IIRC, Zeal and Dash have a deal with eachother - since Dash has no plans for non-mac devices, Dash told zeal the docsets can be used free of charge as long as zeal does not provide release builds on Mac. I believe you can build zeal on mac on your own.
Otherwise is it probably best to look for a specific tool for the type of docs and then look through the GitHub submissions to the user-generated docset submissions for clues for specific code bases: https://github.com/Kapeli/Dash-User-Contributions/pulls?q=is...
I’m a happy user of Dash (macOS) for years now. Sadly Zeal is not 100% the same in terms of integration etc. at least I never got it running on windows and Linux like on Mac. I only use hot key setup (alt-space in my case) No fancy ide hot keys and such.
There used to be some controversy (around 2015) when the author (single dev) put out yet another breaking version with new license upgrades. The free version was artificially slowed down. He added a new search backend and wanted to be compensated. So all users had to pay again. I upgraded 3 or 4 times. I think it’s a great tool that solves a problem. Some feel that he only wrote a parser/display tool and that the price is too high. I wished I came up with the idea though ;)
The point of Zeal is downloadable docsets for offline usage (cppreference, MDN, GNOME docs, etc.), whereas Obsidian is more of a personal wiki you fill yourself AFAIU.
I've tried to use an offline documentation browser a few times before (Dash on Mac) but have never really been able to get into the habit of using it. I generally just end up Googling for what I'm looking for. Outside of low-connectivity situations, what benefits do people find with these viewers?
I actually only started using Zeal during the last few months...but similar to you, the trap i fall into is that muscle memory has not been built up with me to *remember* to check zeal before resorting to a search engine. However, those few times that i *did* remember to use zeal, for me it was really great, solid experience!
For me, the combination of Dash and Alfred is the productivity boost. Alfred makes it very easy to search documentation in Dash. You can have unique keywords in Alfred to target specific packages in Dash. For example, “guava: ImmutableList” or “sidekiq: Client”. I find it especially useful with Dash on a secondary monitor while the editor is on the primary so that both are visible at the same time.
I don’t think there really is a significant difference, unless you’re already using Alfred. I’m an Alfred user and it’s kind of the “start everything place” window for me, the system-wide equivalent of a text editor’s command palette, a CLI for the GUI.
Agreed. I just tried out the Dash hot key and it’s basically the same. I’m tempted to claim the Alfred integration is better but that’s probably just me being a user of Alfred.
I have felt the same way, and curious to what others say about it. I assume the problem I have is that I am not always good at asking the questions of the documentation that I mean, and Google is good at inferring my meaning. More often than not, I don't just need the method signature, but some narrative around what and why. But I try things like Dash again when they come up, or moments like this. To your question, offline browsing is the biggest benefit I see. Long plane ride ahead, or cruise, or train ride? Take your doc with you.
Google has become a terrible search engine to the point that the first mention of the official documentation will be half a page down with some random version. I have to enter like 3 queries for the most trivial workflow of displaying the official documentation’s relevant pages.
Also, even with high speed internet, it is several seconds at least, while zeal/dash will return it basically instantly.
For many queries, Google offers more of a "ready-made" solution e.g. from a StackOverflow post or blog.
When looking at the offline documentation, I know that I am looking at a supported version (not something ancient or much newer than what is deployed in production) and that I am looking at the "authorative" answer i.e. the "real" docs not some third party comments.
When the program I am developing is expected to run correctly even in the presence of errors, it makes a lot of sense to me to consult the authorative documentation rather than "the web" which rarely covers all of the possible corner cases.
This software on Windows really is great (as of 1 year ago) specifically the font aliasing and size didn't match the rest of the system. It was way Smaller to the point of being unreadable for me.
A program on the bus without internet access so this is just perfect. I often download whole websites for this reason or bit better you can print pages off as PDF documents.
I wish I could use Zeal to browse the Apple documentation as well, but unfortunately that’s exclusive to Dash.
I’ve even paid for Dash to get that feature, but no longer use it due to some UI changes in the latest version that add extra clicks for each search query, making the UI inefficient.
Zeal seems to have be inspired by the old and efficient Dash UI, but I can’t have both that and the Apple docs from what I can tell.
The communication with the author (Bogdan) has unfortunately been lacking, taking very long to reply (months) and at best confirming the issues but without any plans to fix them.
In the old days people had locally installed man pages. Documentation or manuals should be delivered locally by default.
It's handy for when you are traveling and have no mobile internet connection, I've been in the alps where there was no network connection at all. It was very good to have everything I want to lookup (wikipedia, devdocs, cached browser history, epubs, stackoverflow) local.
I can imagine it's handy to maintain focus as well, no internet distraction.
For people who can't affort an network connection it's heaven.
Instead of 'sad and unlucky' I'd say 'smart and lucky'.
I would appreciate it when Devhelp (Gtk) allows the user to install further docs. The requirement to place docs somewhere in “/usr/share” is obvious but doesn’t fit the user needs.
111 comments
[ 0.23 ms ] story [ 315 ms ] threadGive me local HTML files I can stash in my filesystem. I actually just use wget to recursively archive entire documentation sites to local folders and serve them up with python's built in web browser. It's the only way to be sure I have accurate and up to date offline docs.
Apparently devdocs does have an API to download docsets. I just installed the Emacs package that someone recommended in another thread and it let me download the docs.
Since the devdocs representation is so standardized, I have wondered if I could dump their database into SQLite and browse it with datasette. Should even be able to maintain text searching.
Is the Zeal code open source enough that one could change the backend by replacing a small number of data access subroutines?
I think all you would need to change is setter code, since getter code wouldn’t be part of the interface. I think Zeal doesn’t write back any data, right ?
With Chrome based browsers this seems to happen usually on browser restarts after version upgrades, however With Firefox I have never had such issue
There seems to be an Electron Desktop client: https://github.com/gengjiawen/electron-devdocs
If we were grown ups, all software authors/vendors would be providing their reference docs in a standardised form, findable, downloadable and displayable by a wide range of tooling, consistent across languages, IDEs and platforms. Zeal is the closest we have, and it's a noble effort, but IME it doesn't solve the problem well enough to be useful because there's no buy-in from the people producing the docs.
(First to mention ChatGPT gets slapped with a wet fish. Just try me.)
To stay on topic, I feel the pain: Zeal is so nice I curse when I need to look up something in the docs that aren't supported (Django REST Framework, in my case), since they use a different doc framework and can't be easily prepared for Dash/Zeal.
Back in the days of yore, software engineering teams led by greybeards used to be conservative in what dependencies they import into the projects. Those days are gone! Everyone imports everything today without any discerning eye.
That's even considered a feature today! If you don't have a language package manager that allows you to transparently import tons of stuff you've never heard of, then the language is considered crap.
I wonder why this trend is happening, especially when python in particular has a bunch of standards and tools to make generating full API docs pretty straightforward.
I also get the sense that there is a growing movement among programmers that API reference documentation is useless, or not worth putting effort into, because it's possible to go out of sync with the code and "nobody reads that anyway". I've heard people say things like "if you're advanced enough to read reference documentation, you're better off just reading the source anyway." It seems to be rooted in some kind of combination of extreme cynicism, a distorted sense of how people who aren't raw beginners learn to do things, and of a kind of false minimalism, wherein API documentation is old fuddy-duddy stuff for Java and C++ developers, and the new friendly easy way is to just read the examples. Such libraries also seem to exhibit a poor separation of public and private interfaces, so maybe it's just a reflection of people being bad at designing libraries.
I normally do end up reading source code, but it often introduces unnecessary hassle because while it's great for "what does this function do?" type of stuff, it really falls down when you want to know "what type of functions fall under this module" since you end up navigating up and down through a lot of imports that make sense for code organization but are abstracted away at the point of use.
* https://writethedocs.slack.com/archives/C6D77HJ4F/p168556139...
* https://www.reddit.com/r/technicalwriting/comments/13wvmbt
There has been controversy in the past about the tool since it is a glorified man page reader. The author even shared at one point his earnings and what he is doing with it.
And no there is no zeal for macOS. I don’t know the details behind that deal. I can only say that zeal is not as good as dash. The integration into macOS is way smoother than what one gets on windows and Linux. I tried all versions.
You don’t need to build it yourself, there is a brew formula.
I'd be happy to hear of others, but the situation for generating docs is pretty dire right now (as far as I can tell).
When you're starting with Doxygen documentation: https://github.com/chinmaygarde/doxygen2docset or https://pypi.org/project/doxytag2zealdb. If it's Sphinx-like, then https://github.com/hynek/doc2dash
Otherwise is it probably best to look for a specific tool for the type of docs and then look through the GitHub submissions to the user-generated docset submissions for clues for specific code bases: https://github.com/Kapeli/Dash-User-Contributions/pulls?q=is...
There used to be some controversy (around 2015) when the author (single dev) put out yet another breaking version with new license upgrades. The free version was artificially slowed down. He added a new search backend and wanted to be compensated. So all users had to pay again. I upgraded 3 or 4 times. I think it’s a great tool that solves a problem. Some feel that he only wrote a parser/display tool and that the price is too high. I wished I came up with the idea though ;)
I recently discovered devdocs.io and the emacs integration[1] and like it so far.
[1] https://github.com/astoff/devdocs.el
But yeah, it took me a while to get into the habit as well, and the benefit was pretty small. It mainly just feels nice.
A more limited and focused selection of documentation gets me exactly what I need. It's also a lot faster then documentation websites.
I stop and think about the issue instead of just googling for an answer.
Also, I removed the wifi card from my laptop so I can work from a room without ethernet letting myself get distracted by the internet.
Also, even with high speed internet, it is several seconds at least, while zeal/dash will return it basically instantly.
When looking at the offline documentation, I know that I am looking at a supported version (not something ancient or much newer than what is deployed in production) and that I am looking at the "authorative" answer i.e. the "real" docs not some third party comments.
When the program I am developing is expected to run correctly even in the presence of errors, it makes a lot of sense to me to consult the authorative documentation rather than "the web" which rarely covers all of the possible corner cases.
I’ve even paid for Dash to get that feature, but no longer use it due to some UI changes in the latest version that add extra clicks for each search query, making the UI inefficient.
Zeal seems to have be inspired by the old and efficient Dash UI, but I can’t have both that and the Apple docs from what I can tell.
See https://news.ycombinator.com/item?id=25434191 for prior discussion about my experience.
I would appreciate it when Devhelp (Gtk) allows the user to install further docs. The requirement to place docs somewhere in “/usr/share” is obvious but doesn’t fit the user needs.