:toc: macro :experimental:

Doc Browser is an API documentation browser with support for DevDocs, Dash and Hoogle, written in Haskell and QML.

The GUI looks like this:

image:asset/interface-annotated.png[Main Interface]

link:asset/interface-hoogle.png[This one] is the interface for Hoogle.

link:asset/interface-torch.png[This one] is the interface for PyTorch.

toc::[]

== Features

• Native desktop application
• Works offline
• link:#speed[Near real-time] fuzzy search
• Easy-to-type shortcuts
• DevDocs support
• Dash support (incomplete)
• Hoogle integration
• Customizable
• link:#http-interface[HTTP interfaces]
• link:https://github.com/qwfy/doc-browser-nvim[Neovim integration]. Editor integration is just a HTTP request away

== Current Status

• 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

== Contributions Are Welcome

Several other features are planned but I haven't got the time to implement or improve them, including: (in no particular order)

1. Packaging for various Linux distributions
2. Add "Back" and "Forward" navigation button to the GUI (preferably to the tab bar), like the ones in the web browsers
3. Better support for Dash docsets (the current support is incomplete and hacky)
4. Better support for Haskell docs (eg. support for individual package)
5. Add a GUI to manage the docsets (including the ability to auto update the installed docsets)
6. 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.

== Installation

=== Arch Linux

There is a https://aur.archlinux.org/packages/doc-browser-git/[PKGBUILD] available on AUR.

=== Other Linux Distros

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:

1. This application uses http://qt-project.org/[Qt 5], make sure you have it installed. You also need https://wiki.qt.io/QtWebEngine[QtWebEngine], install it if it doesn't come with your Qt installation.
2. Install the Haskell tool https://docs.haskellstack.org/en/stable/install_and_upgrade/[stack].
3. The build process depends on several executables: c2hs, alex and happy, you can either install it using your package manager, or use the instruction given below.
4. Install other dependencies mentioned in the depends section in https://github.com/qwfy/doc-browser/blob/master/aur/PKGBUILD[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 install mathjax if you don't intend to use Hoogle.

Finally, run these commands in the shell to build and install the application:

[source,bash]

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 http://www.gekkou.co.uk/software/hsqml/[this page] help? Especially the Requirements and Installation section.
• Open an issue.

Optionally, install the executable xsel or xclip for the kbd:[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 kbd:[Ctrl+/] shortcut (send query to Google) to work.

Optionally, generate a completion script for your shell with:

[source,bash]

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-script

=== Install DevDocs' Docset

To install DevDocs' docset, invoke:

[source,bash]

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 versions

This will download docsets from devdocs.io, and install them to XDG_CONFIG/doc-browser/DevDocs.

=== Install Dash's Docset

To install Dash's docset, invoke:

[source,bash]

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-Contributions

=== Enable Hoogle Support

To support Hoogle, this application creates a Hoogle database from a documentation archive, which can be done by these steps:

1. Find out which documentation archive you want to use. The Hoogle support is tested on archives provided by https://www.stackage.org[Stackage], like https://s3.amazonaws.com/haddock.stackage.org/lts-10.8/bundle.tar.xz[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 https://github.com/commercialhaskell/stackage/issues/4098), so you have to generate the archive yourself.
2. Invoke the following installation command, this will unpack the archive to XDG_CONFIG/doc-browser/Hoogle/COLLECTION, and creates a Hoogle database XDG_CONFIG/doc-browser/Hoogle/COLLECTION.hoo for it, (doc-browser's Hoogle doesn't interfere with your system Hoogle in any way):

[source,bash]

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.

3. 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 link:#configuration[Configuration] section for instructions.

=== Start the Application

If you installed the application from AUR, you can either start it with the shipped .desktop file, or with:

[source,bash]

doc-browser

If you installed from source, start it with:

[source,bash]

doc-browser

if you see any errors, it's probably due to the missing of dependencies

You 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.

== Offline Support

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.

=== DevDocs 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

=== Dash Dash's docset works offline out of the box.

=== Hoogle If a MathJax distribution is found at /usr/share/mathjax (configurable), then the Hoogle documentations will work offline. (If you installed from AUR, you already have it.)

== GUI

• 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.

=== Commands

These commands are provided by default, you can customize them by following the instructions in the link:#configuration[Configuration] section.

[cols=",",options="header",] |=== | 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 |===

=== Shortcuts

[cols="3",options="header",] |=== | Key | Effect | Comment | kbd:[/] | focus the search box | | kbd:[Ctrl+I] | focus and clear the search box, but keep the command, if any | e.g. before: "/pyfoo"; after: "/py" | kbd:[Enter] or kbd:[Down] | accept query and select the first match | when in the search box | kbd:[A]kbd:[S]kbd:[D]kbd:[F]kbd:[W]kbd:[E]kbd:[R]kbd:[T]kbd:[C] | open match 1-9 | | kbd:[G+A]kbd:[S]kbd:[D]kbd:[F]kbd:[W]kbd:[E]kbd:[R]kbd:[T]kbd:[C] | open match 10-18 | | kbd:[V+A]kbd:[S]kbd:[D]kbd:[F]kbd:[W]kbd:[E]kbd:[R]kbd:[T]kbd:[C] | open match 19-27 | | kbd:[J] | select the next match | | kbd:[K] | select the previous match | | kbd:[Enter] | open the selected match | when the selected item has focus | kbd:[Tab] or kbd:[Down] | select the next match | when the selected item has focus | kbd:[Shift+Tab] or kbd:[Up] | select the previous match | when the selected item has focus | kbd:[1]kbd:[2]kbd:[3]kbd:[4]kbd:[5]kbd:[6]kbd:[7]kbd:[8]kbd:[9]kbd:[0] | go to the corresponding tab | | kbd:[Alt+L] | go to the next tab | | kbd:[Alt+H] | go to the previous tab | | kbd:[Ctrl+W] | close the current tab | | kbd:[Y] | copy the selected match to clipboard | need executable xsel or xclip | kbd:[M] | copy the module of the selected match to clipboard | only for Hoogle. need executable xsel or xclip | kbd:[P] | copy the package of the selected match to clipboard | only for Hoogle. need executable xsel or xclip | kbd:[Ctrl+/] | send query to Google | e.g. kbd:[Ctrl+/] on "/pyfoo" will search Google for "Python foo"; need executable xdg-open | kbd:[Ctrl+F] | open or focus page search | | kbd:[Alt+N] | find next in page search | | kbd:[Alt+P] | find previous in page search | | kbd:[Esc] | close page search | when in search box |===

Depending on your platform, kbd:[Ctrl+U] can be used to clear the input box, just like in readline.

== Configuration

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.yaml in the root of the source repository

== HTTP Interface

You can interact with this application using HTTP requests.

API documentation can be found at:

• https://qwfy.github.io/doc-browser/http-interface.html
• or, doc-browser --print-api

== Speed

As can be seen from the below (slighly outdated) benchmark, it takes less than 50ms to search through 39,499 entries.

image:prof/compare of speed of several implementations - no edit distance.png[Prof]

== Credits and License

This application is written by [email protected], 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 https://github.com/Thibaut[Thibaut Courouble] and https://github.com/Thibaut/devdocs/graphs/contributors[other contributors] of https://github.com/Thibaut/devdocs[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 https://github.com/ndmitchell[Neil Mitchell] for the great https://github.com/ndmitchell/hoogle[Hoogle]. The Hoogle support receives https://github.com/qwfy/doc-browser/issues/2[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 https://github.com/Kapeli/Dash-iOS[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 https://kapeli.com/dash[Dash].

== Known Problems and Solutions

Problem: On KDE, kbd:[Ctrl+/] is taking too long to open the browser.

Solution: This application uses xdg-open to open the browser. Try https://bugs.kde.org/show_bug.cgi?id=364662#c3[this workaround].

Problem: The font in the documentation is too big or too small.

Solution: Tweak the configuration WebEngineZoomFactor, see the link:#configuration[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 https://kb.froglogic.com/display/KB/Problem+-+Bringing+window+to+foreground+%28Qt%29[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 :(

== FAQ 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.

== Tips

• Typically, you can omit characters such as '_' (those require you holding kbd:[Shift] to type) from your query string, your pinky might thank you for that.