Doc Browser is an API documentation browser with support for DevDocs, Dash and Hoogle, written in Haskell and QML.
The GUI looks like this:
This one is the interface for Hoogle.
This one is the interface for PyTorch.
-
Native desktop application
-
Works offline
-
Near real-time fuzzy search
-
Easy-to-type shortcuts
-
DevDocs support
-
Dash support (incomplete)
-
Hoogle integration
-
Customizable
-
Neovim integration. Editor integration is just a HTTP request away
-
The main GUI is suitable for daily use
-
Docset management is usable, but needs polishing
-
Packaging for OSes other than Arch Linux need to be added
-
I use this application every day and happy with it
Several other features are planned but I haven’t got the time to implement or improve them, including: (in no particular order)
-
Packaging for various Linux distributions
-
Add "Back" and "Forward" navigation button to the GUI (preferably to the tab bar), like the ones in the web browsers
-
Better support for Dash docsets (the current support is incomplete and hacky)
-
Better support for Haskell docs (eg. support for individual package)
-
Add a GUI to manage the docsets (including the ability to auto update the installed docsets)
-
Integration with diigo, or send the selection to a note service, like cherrytree or Evernote
If you wish to contribute to feature 3, 4 and 5, please do contact me via Github issue before doing it.
There is a PKGBUILD available on AUR.
You can build this application from source, which isn’t a pleasant experience. Packaging for popular OSes/package managers are welcome.
Follow these steps to install from source:
-
This application uses Qt 5, make sure you have it installed. You also need QtWebEngine, install it if it doesn’t come with your Qt installation.
-
Install the Haskell tool stack.
-
The build process depends on several executables:
c2hs,alexandhappy, you can either install it using your package manager, or use the instruction given below. -
Install other dependencies mentioned in the
dependssection in this file, the package name for your package manager may be different with the provided one. You can either install them now, or later in a trial-and-error manner. You don’t need to installmathjaxif you don’t intend to use Hoogle.
Finally, run these commands in the shell to build and install the application:
git clone 'https://github.com/qwfy/doc-browser.git'
cd doc-browser
# optionally, install these executables if not already installed:
# stack install c2hs
# stack install alex
# stack install happy
# build and install this application, this will take a while
# if this step fails, then you probably missed some dependencies,
# your can examine the error message to see which dependencies are missing
stack install
echo "binary installed to $(stack path --local-bin)"If you have trouble building this application, you can:
-
Is it a dependency problem?
-
Does this page help? Especially the Requirements and Installation section.
-
Open an issue.
Optionally, install the executable xsel or xclip for the Y shortcut
(copy the selected match to clipboard) to work.
Optionally, install the executable xdg-open (provided by package
xdg-utils on Arch Linux) for the Ctrl+/ shortcut (send query to
Google) to work.
Optionally, generate a completion script for your shell with:
# completion will be available in a new shell
doc-browser --bash-completion-script `which doc-browser` > /etc/bash_completion.d/doc-browser.bash
# or source them manually:
source <(doc-browser --bash-completion-script `which doc-browser`)
# for Zsh and Fish, there is:
# --zsh-completion-script
# --fish-completion-scriptTo install DevDocs' docset, invoke:
doc-browser --install-devdocs DOC COLLECTION==VERSION ..
# e.g.
# doc-browser --install-devdocs python Python==2.7.13
# will install both the latest version of Python 3.x and Python 2.7.13
# use
# doc-browser --list-remote-devdocs
# to query available docsets and versionsThis will download docsets from devdocs.io, and install them to
XDG_CONFIG/doc-browser/DevDocs.
To install Dash’s docset, invoke:
doc-browser --install-dash COLLECTION ..
# e.g.
# doc-browser --install-dash Erlang
# will install the Erlang docset
# use
# doc-browser --list-remote-dash
# to query available docsets
# This will download docsets from kapeli.com, and install them to `XDG_CONFIG/doc-browser/Dash`.
# to install from a locally built archive,
# or those in https://github.com/Kapeli/Dash-User-Contributions,
# use:
doc-browser --install-dash COLLECTION --local-archive ABSOLUTE_PATH_TO_DOCSET_TGZ --version VERSION
# e.g.
# doc-browser --install-dash PyTorch --local-archive $(pwd)/PyTorch.tgz --version 1.4.0
# will install the docset for PyTorch, version 1.4.0
# where PyTorch.tgz is generated according to:
# https://github.com/Kapeli/Dash-User-ContributionsTo support Hoogle, this application creates a Hoogle database from a documentation archive, which can be done by these steps:
-
Find out which documentation archive you want to use. The Hoogle support is tested on archives provided by Stackage, like this one, which can be found at: https://www.stackage.org/lts-10.8. You can use other archives as well, as long as the unpacked archive can be read by
hoogle generate --local=dir_to_unpacked_archive, but this is untested. NOTE that stackage no longer provides download links for these kinds of archives, (see commercialhaskell/stackage#4098), so you have to generate the archive yourself. -
Invoke the following installation command, this will unpack the archive to
XDG_CONFIG/doc-browser/Hoogle/COLLECTION, and creates a Hoogle databaseXDG_CONFIG/doc-browser/Hoogle/COLLECTION.hoofor it, (doc-browser’s Hoogle doesn’t interfere with your system Hoogle in any way):
doc-browser --install-hoogle URL COLLECTION
# e.g. doc-browser --install-hoogle 'https://s3.amazonaws.com/haddock.stackage.org/lts-10.8/bundle.tar.xz' lts-10.8
#
# URL is where to read the archive.
# It can also be a local file,
# which I suggest you to use if you have a bad network connection,
# since the download function included in this program is pretty savage at this stage.
#
# See `doc-browser --help` for more
#
# Don't panic if you see a lot of lines that look like this
# at the begining and the ending of the generation
# (for the above lts-10.8, there are 43 of these):
#
# temporarily relocate x to x.__co.aixon.docbrowser-tempfile__, for x in:
# /home/user/.config/doc-browser/Hoogle/lts-10.8/prologue.txt
# ...
# move x.__co.aixon.docbrowser-tempfile__ back to x, for x in:
# /home/user/.config/doc-browser/Hoogle/lts-10.8/prologue.txt
# ...
#
# These are necessary to work around a Hoogle issue.-
Prefix or suffix a search with "/hh" to query Hoogle, like this:
/hh[a]→Int→[a]. Multiple databases are also supported, you need to add a command to specify which database you want to access to, see the Configuration section for instructions.
If you installed the application from AUR, you can either start it with the shipped .desktop file, or with:
doc-browserIf you installed from source, start it with:
doc-browser
# if you see any errors, it's probably due to the missing of dependenciesYou can also start it with doc-browser.desktop, found in the root
of this repository. Icon is available if you copy icon.svg to a location
such as /usr/share/icons/doc-browser.svg.
The documentation files themselves are downloaded to your disk when
doc-browser --install-devdocs, doc-browser --install-dash
or doc-browser --install-hoogle is invoked, however, to display
the documentation, some additional Cascading Style Sh*t or
JavaScript files are needed, some of these are not packaged with
the documentation files.
To make DevDocs' docsets work fully offline:
-
Start the application after
doc-browser --install-devdocs -
Search for anything, and open any match
-
When the tab is opened and the documentation is correctly displayed, all necessary files are cached, DevDocs' docsets work offline now
-
When the application starts, you will see a blank screen, you can start typing to search.
-
Prefix or suffix a search string with "/py", (e.g. "/pyabspath", "abspath/py"), will limit the search to the Python docset provided by DevDocs, more commands are available, see below.
-
Number of tabs will peak at 10, open one more tab will close the left-most one.
-
Various keyboard shortcuts are available, see below.
These commands are provided by default, you can customize them by following the instructions in the Configuration section.
| Command | Effect |
|---|---|
py |
Limit search to DevDocs' Python 3.x |
p2 |
Limit search to DevDocs' Python 2.x |
tf |
Limit search to DevDocs' TensorFlow |
np |
Limit search to DevDocs' NumPy |
pd |
Limit search to DevDocs' pandas |
mp |
Limit search to DevDocs' Matplotlib |
go |
Limit search to DevDocs' Go |
hs |
Limit search to DevDocs' Haskell |
pg |
Limit search to DevDocs' PostgreSQL |
sl |
Limit search to DevDocs' SQLite |
th |
Limit search to Dash’s PyTorch |
rs |
Limit search to Dash’s Rust |
er |
Limit search to Dash’s Erlang |
sp |
Limit search to Dash’s SciPy |
hh |
Perform search with Hoogle |
| Key | Effect | Comment |
|---|---|---|
/ |
focus the search box |
|
Ctrl+I |
focus and clear the search box, but keep the command, if any |
e.g. before: "/pyfoo"; after: "/py" |
Enter or Down |
accept query and select the first match |
when in the search box |
ASDFWERTC |
open match 1-9 |
|
G+ASDFWERTC |
open match 10-18 |
|
V+ASDFWERTC |
open match 19-27 |
|
J |
select the next match |
|
K |
select the previous match |
|
Enter |
open the selected match |
when the selected item has focus |
Tab or Down |
select the next match |
when the selected item has focus |
Shift+Tab or Up |
select the previous match |
when the selected item has focus |
1234567890 |
go to the corresponding tab |
|
Alt+L |
go to the next tab |
|
Alt+H |
go to the previous tab |
|
Ctrl+W |
close the current tab |
|
Y |
copy the selected match to clipboard |
need executable |
M |
copy the module of the selected match to clipboard |
only for Hoogle. need executable |
P |
copy the package of the selected match to clipboard |
only for Hoogle. need executable |
Ctrl+/ |
send query to Google |
e.g. Ctrl+/ on "/pyfoo" will search Google for "Python foo"; need executable |
Ctrl+F |
open or focus page search |
|
Alt+N |
find next in page search |
|
Alt+P |
find previous in page search |
|
Esc |
close page search |
when in search box |
Depending on your platform, Ctrl+U can be used to clear the input box, just like in readline.
Create the file XDG_CONFIG/doc-browser/config.yaml and edit it.
The file is in YAML format, configurable keys and documentations can be found at:
-
doc-browser --print-default-config -
or
config.yamlin the root of the source repository
You can interact with this application using HTTP requests.
API documentation can be found at:
-
or,
doc-browser --print-api
As can be seen from the below (slighly outdated) benchmark, it takes less than 50ms to search through 39,499 entries.
This application is written by incomplete@aixon.co, and licensed under MPL-2.0.
You can use the icon.svg in the root of this repository as the icon of this application.
Permission is needed if you plan to use it for other purposes.
Many thanks to Thibaut Courouble and other contributors of DevDocs, without their work, this application wouldn’t be possible:
-
This application ships with icons collected by DevDocs.
-
This application uses docsets, along with the corresponding style sheets, produced by DevDocs.
Many thanks to Neil Mitchell for the great Hoogle. The Hoogle support receives helps from him. This application also ships with a little code from the Hoogle project, the modified code is licensed under the BSD license.
Many thanks to Bogdan Popescu for allowing me to use Dash’s docset. This application also ships with icons from the Dash-iOS project. If you are using Mac, please consider Dash.
Problem: On KDE, Ctrl+/ is taking too long to open the browser.
Solution: This application uses xdg-open to open the browser. Try
this workaround.
Problem: The font in the documentation is too big or too small.
Solution: Tweak the configuration WebEngineZoomFactor, see the
Configuration section for instruction.
Problem: HTTP summon interface doesn’t bring the window to front
Solution: Try the section Additional settings for Linux described in here.
Problem: (China users only) Installation of docsets hangs/open documentation shows blank screen.
Solution: devdocs.io or cloudflare.com is blocked by GFW, please use a VPN.
Problem: Install/uninstall some Dash docsets reports error.
Solution: If a docset has / in its name or version, (many Dash docsets do), the installation or uninstallation may not work. This problem is known from the begining, it’s just that I haven’t got time to fix it properly (without introducing un-upgradable changes). Solution: wait for me to fix it :(
Q: Why does this application display at most 27 matches?
A: If your desired match is not in the top 27 matches, then there is probably something wrong with the search algorithm.
Q: Why does this application display at most 10 tabs?
A: If too many tabs are displayed, the tab title would be hard to see on many monitors. Instead of wanting more tabs, try open another instance of this application. The number of maximum tabs will be configurable in future versions, so you can benefit from a large monitor.